ruvnet/ruflo · error

invite code must look like v2.

Error message

invite code must look like v2.<token>

What it means

The federation join tool validates invite codes against /^v2\.[A-Za-z0-9._-]{8,}$/ before doing anything else — deliberately even before the nostr-tools availability check, so a malformed code fails fast and identically regardless of environment. Codes must start with 'v2.' followed by at least 8 allowed characters.

Solutions

1. Copy the full invite code exactly as issued, including the leading 'v2.' prefix and everything after it
2. Strip any wrapping (quotes, trailing whitespace, URL-encoding) and ensure the token is at least 8 characters of letters/digits/dots/underscores/hyphens
3. Request a fresh v2 invite code from the swarm administrator if only an old-format code is available

Example fix

// before
await join({ code: 'abc123' });
// throws: invite code must look like v2.<token>
// after
await join({ code: 'v2.a1B2c3D4e5F6g7H8' });

const INVITE_RE = /^v2\.[A-Za-z0-9._-]{8,}$/;
if (!INVITE_RE.test(code)) throw new Error(`malformed invite code: ${code.slice(0, 6)}...`);

const isValidInviteCode = (code: unknown): code is string =>
  typeof code === 'string' && /^v2\.[A-Za-z0-9._-]{8,}$/.test(code);

try {
  await join({ code });
} catch (e) {
  if (String(e.message).includes('invite code must look like')) {
    console.error('Check the invite code: must be v2. followed by >=8 chars of [A-Za-z0-9._-]');
  } else throw e;
}

When it happens

Trigger: Calling the join tool with a code missing the v2. prefix, an empty/short token (fewer than 8 chars), or a token containing characters outside [A-Za-z0-9._-] (e.g. spaces, '+', '/', URL-encoded characters pasted from a browser).

Common situations: Copying only part of an invite code from chat/email; pasting a URL-wrapped code including percent-encoding; using an old v1-format invite against a tool that only accepts v2.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• channel must be pub: or prv:<16 hex>
• msgType must be alnum + _ - and ≤64 chars
• nodeId must be 16 lowercase hex chars
• actualUsd must be a non-negative finite number
• Agent config must include id, name, and type

AI-assisted analysis of ruvnet/ruflo@2602b642d9 (2026-09-15). Data as JSON: /api/errors/02b5fa0c01abe70b. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/mcp-tools/x-federation-join.ts:68

    setTimeout(() => fin({ ok: false, reason: 'timeout' }), 15000);
  });
}

export const xFederationJoinTools: MCPTool[] = [{
  name: 'x_federation_join',
  description:
    'Join the open swarm federation with YOUR OWN key using an invite code: generates (or reuses) a local Nostr key at ~/.ruflo/nostr.key (0600), redeems the code with a NIP-98-signed claim directly against the relay, proves membership via NIP-42, and returns your pubkey. Use when you have been handed an invite code and want to participate as yourself. Asking an admin to `federation_admit` you instead is wrong for an open swarm because it centralizes onboarding and requires trusting a pubkey out of band; the invite claim binds membership to the key you hold. Never share the invite code publicly — it is a bearer secret.',
  inputSchema: { type: 'object', properties: {
    code: { type: 'string', description: 'Invite code (v2.…) received privately from a member/admin.' },
    relayHttp: { type: 'string', description: 'Relay HTTPS base for the claim; takes precedence over RUFLO_X_RELAY_HTTP.' },
    relayWs: { type: 'string', description: 'Relay wss URL for NIP-42; takes precedence over RUFLO_X_RELAY_WS.' },
    keyFile: { type: 'string', description: 'Key file path; takes precedence over RUFLO_NOSTR_KEY_FILE (default ~/.ruflo/nostr.key).' } }, required: ['code'] },
  handler: async (input) => {
    const i = input as { code: string; relayHttp?: string; relayWs?: string; keyFile?: string };
    const nt = await loadNostrTools();
    // Validate input before the optional-dependency check so a bad code fails fast and identically
    // whether or not nostr-tools is present.
    if (!/^v2\.[A-Za-z0-9._-]{8,}$/.test(i.code)) throw new Error('invite code must look like v2.<token>');
    if (!nt) return { degraded: true, reason: 'nostr-tools not installed', hint: 'npm i -g nostr-tools  (secp256k1 signing is not in node:crypto)' };
    const { sk, pubkey, created } = loadOrCreateKey(nt, i.keyFile);
    const url = `${HTTP_BASE(i.relayHttp)}/api/invites/claim`; const body = JSON.stringify({ code: i.code });
    const r = await fetch(url, { method: 'POST', headers: { Authorization: nip98Header(nt, sk, url, 'POST', body), 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(20_000) });
    const claim = (await r.json().catch(() => ({}))) as { role?: string; error?: string; message?: string };
    if (!r.ok) throw new Error(`claim rejected (${r.status}): ${claim.error ?? claim.message ?? 'unknown'}`);
    const auth = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
    return { ok: auth.ok, pubkey, keyCreated: created, role: claim.role ?? 'member', membershipVerified: auth.ok, ...(auth.ok ? {} : { reason: auth.reason }),
      next: 'Publish kind-1 events tagged ["t","ruflo-swarm"] — or run `ruflo federation sync` to read the swarm.' };
  },
}];

View on GitHub (pinned to 2602b642d9)