ruvnet/ruflo · error · Error

RVFP header magic mismatch

Error message

RVFP header magic mismatch

What it means

Thrown by parsePatchHeader() after the header JSON parsed successfully, but the parsed object's magic field is not the literal 'RVFP'. This is a defence-in-depth check: the binary preamble magic passed, yet the embedded JSON header disagrees about the format identity. It catches tampered, hand-assembled, or format-confused headers where the binary framing was correct but the JSON payload was swapped.

Source

Thrown at v3/@claude-flow/cli/src/appliance/rvfa-distribution.ts:199

      header.signedBy = opts.signedBy;
    }
    const hJson = Buffer.from(JSON.stringify(header), 'utf-8');
    const magic = Buffer.from('RVFP');
    const ver = Buffer.alloc(4); ver.writeUInt32LE(RVFP_VERSION, 0);
    const hLen = Buffer.alloc(4); hLen.writeUInt32LE(hJson.length, 0);
    return Buffer.concat([magic, ver, hLen, hJson, payload, sha256B(payload)]);
  }

  static parsePatchHeader(buf: Buffer): RvfpHeader {
    if (buf.length < PRE) throw new Error('Buffer too small for RVFP preamble');
    const magic = buf.subarray(0, 4).toString('ascii');
    if (magic !== 'RVFP') throw new Error(`Invalid RVFP magic: "${magic}"`);
    const ver = buf.readUInt32LE(4);
    if (ver !== RVFP_VERSION) throw new Error(`Unsupported RVFP version: ${ver}`);
    const hLen = buf.readUInt32LE(8);
    if (PRE + hLen > buf.length) throw new Error('Buffer too small for declared header');
    const h = JSON.parse(buf.subarray(PRE, PRE + hLen).toString('utf-8')) as RvfpHeader;
    if (h.magic !== 'RVFP') throw new Error('RVFP header magic mismatch');
    return h;
  }

  static async verifyPatch(buf: Buffer): Promise<PatchVerifyResult> {
    const errors: string[] = [];
    let header: RvfpHeader;
    try { header = RvfaPatcher.parsePatchHeader(buf); } catch (e) {
      const empty: RvfpHeader = {
        magic: 'RVFP', version: 0, targetApplianceName: '', targetApplianceVersion: '',
        targetSection: '', patchVersion: '', created: '', newSectionSize: 0,
        newSectionSha256: '', compression: 'none',
      };
      return { valid: false, header: empty, errors: [(e as Error).message] };
    }
    const { start, end, section } = patchData(buf);
    if (end < start) {
      errors.push('Patch too small: no room for section data and footer');
      return { valid: false, header, errors };

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Regenerate the patch with RvfaPatcher.createPatch() which always sets header.magic = 'RVFP'.
2. Audit any code that constructs RvfpHeader objects by hand to ensure magic is set.
3. Discard the patch — a mismatched header magic indicates the producer was buggy or the file was tampered with.
4. If interoperating with another producer, require they emit magic='RVFP' in the JSON header.

function isRvfpHeaderObject(h: unknown): h is RvfpHeader {
  return typeof h === 'object' && h !== null && (h as any).magic === 'RVFP';
}

try {
  const header = RvfaPatcher.parsePatchHeader(buf);
} catch (e) {
  if (/RVFP header magic mismatch/.test((e as Error).message)) {
    throw new Error('Patch header JSON is inconsistent (magic != RVFP); regenerate with createPatch()');
  }
  throw e;
}

When it happens

Trigger: A buffer whose first 12 bytes and header-length are valid and the JSON region parses, but the JSON object's magic field is missing, misspelled, or set to a different value (e.g. 'RVFA'). Usually indicates manual construction or cross-contamination between RVFA and RVFP serialization code.

Common situations: A tool that serializes both RVFA appliances and RVFP patches accidentally writes an RVFA-style header object into a patch buffer; an adversary or fuzzer mutates the header JSON without fixing the magic; a test fixture copied from the wrong format.

Related errors

• Buffer too small for RVFP preamble
• Invalid RVFP magic: "${magic}"
• Unsupported RVFP version: ${ver}
• Buffer too small for declared header
• Header length extends beyond buffer

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/a6e83e4f67cc214e. Report an issue: GitHub.