π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ADR-058): Phase 3-4 β GGUF engine, Ed25519 signing, IPFS distribution, hot-patch
rUv4c53ab9f5bcf
diff --git a/v3/@claude-flow/cli/src/appliance/gguf-engine.ts b/v3/@claude-flow/cli/src/appliance/gguf-engine.tsnew file mode 100644index 0000000000..4a2268339b--- /dev/null+++ b/v3/@claude-flow/cli/src/appliance/gguf-engine.ts@@ -0,0 +1,442 @@+/**+ * ruvLLM GGUF Inference Engine -- Pure Node.js GGUF Model Interface+ *+ * Provides:+ * 1. GGUF binary header parsing (metadata without loading weights)+ * 2. Model loading abstraction (node-llama-cpp when available, metadata-only fallback)+ * 3. Token generation interface with async iterator streaming+ * 4. KV-cache persistence to RVF-compatible binary format+ *+ * Zero external dependencies. node-llama-cpp is an optional peer.+ *+ * @module @claude-flow/cli/appliance/gguf-engine+ */++import { open, readFile, writeFile, stat as fsStat } from 'node:fs/promises';+import { createHash } from 'node:crypto';+import { basename } from 'node:path';++// ββ GGUF Metadata Value Types βββββββββββββββββββββββββββββββ++const enum GgufValueType {+ UINT8 = 0, INT8 = 1, UINT16 = 2, INT16 = 3, UINT32 = 4, INT32 = 5,+ FLOAT32 = 6, BOOL = 7, STRING = 8, ARRAY = 9, UINT64 = 10, INT64 = 11, FLOAT64 = 12,+}++const GGUF_MAGIC = 0x46554747; // "GGUF" in little-endian+const RVKV_MAGIC = 0x564B5652; // "RVKV" in little-endian+const RVKV_VERSION = 1;++// ββ Public Interfaces βββββββββββββββββββββββββββββββββββββββ++export interface GgufMetadata {+ magic: string;+ version: number;+ tensorCount: number;+ kvCount: number;+ architecture?: string;+ name?: string;+ contextLength?: number;+ embeddingLength?: number;+ blockCount?: number;+ vocabSize?: number;+ quantization?: string;+ fileSize: number;+ metadata: Record<string, unknown>;+}++export interface GgufEngineConfig {+ contextSize?: number;+ maxTokens?: number;+ temperature?: number;+ kvCachePath?: string;+ verbose?: boolean;+}++export interface GenerateRequest {+ prompt: string;+ model?: string;+ maxTokens?: number;+ temperature?: number;+ stream?: boolean;+ stopSequences?: string[];+}++export interface GenerateResponse {+ text: string;+ model: string;+ tokensUsed: number;+ latencyMs: number;+ metadataOnly: boolean;+}++// ββ Internal Buffer Reader ββββββββββββββββββββββββββββββββββ++/** Stateful cursor over a Buffer for sequential binary reads. */+class BufferReader {+ private offset = 0;+ constructor(private buf: Buffer) {}+ get remaining(): number { return this.buf.length - this.offset; }++ readU8(): number { const v = this.buf.readUInt8(this.offset); this.offset += 1; return v; }+ readI8(): number { const v = this.buf.readInt8(this.offset); this.offset += 1; return v; }+ readU16(): number { const v = this.buf.readUInt16LE(this.offset); this.offset += 2; return v; }+ readI16(): number { const v = this.buf.readInt16LE(this.offset); this.offset += 2; return v; }+ readU32(): number { const v = this.buf.readUInt32LE(this.offset); this.offset += 4; return v; }+ readI32(): number { const v = this.buf.readInt32LE(this.offset); this.offset += 4; return v; }+ readF32(): number { const v = this.buf.readFloatLE(this.offset); this.offset += 4; return v; }+ readF64(): number { const v = this.buf.readDoubleLE(this.offset); this.offset += 8; return v; }+ readU64(): bigint { const v = this.buf.readBigUInt64LE(this.offset); this.offset += 8; return v; }+ readI64(): bigint { const v = this.buf.readBigInt64LE(this.offset); this.offset += 8; return v; }+ readU64AsNumber(): number { return Number(this.readU64()); }+ readBool(): boolean { return this.readU8() !== 0; }++ /** GGUF string: [length u64 LE][utf-8 bytes]. */+ readString(): string {+ const len = this.readU64AsNumber();+ if (len === 0) return '';+ if (len > this.remaining) throw new Error(`String length ${len} exceeds remaining buffer`);+ const s = this.buf.toString('utf-8', this.offset, this.offset + len);+ this.offset += len;+ return s;+ }+}++// ββ GGUF Value Reading ββββββββββββββββββββββββββββββββββββββ++/** Read a typed scalar from the buffer (shared by value and array-element readers). */+function readScalar(reader: BufferReader, t: number): unknown {+ switch (t) {+ case GgufValueType.UINT8: return reader.readU8();+ case GgufValueType.INT8: return reader.readI8();+ case GgufValueType.UINT16: return reader.readU16();+ case GgufValueType.INT16: return reader.readI16();+ case GgufValueType.UINT32: return reader.readU32();+ case GgufValueType.INT32: return reader.readI32();+ case GgufValueType.FLOAT32: return reader.readF32();+ case GgufValueType.BOOL: return reader.readBool();+ case GgufValueType.STRING: return reader.readString();+ case GgufValueType.UINT64: return Number(reader.readU64());+ case GgufValueType.INT64: return Number(reader.readI64());+ case GgufValueType.FLOAT64: return reader.readF64();+ default: return undefined;+ }+}++/** Read a single GGUF typed value (scalar or array) from the buffer. */+function readGgufValue(reader: BufferReader): unknown {+ const valueType = reader.readU32();+ if (valueType === GgufValueType.ARRAY) {+ const elemType = reader.readU32();+ const len = reader.readU64AsNumber();+ const arr: unknown[] = [];+ for (let i = 0; i < len; i++) {+ const v = readScalar(reader, elemType);+ if (v === undefined) throw new Error(`Unknown GGUF array element type: ${elemType}`);+ arr.push(v);+ }+ return arr;+ }+ const v = readScalar(reader, valueType);+ if (v === undefined) throw new Error(`Unknown GGUF value type: ${valueType}`);+ return v;+}++// ββ GGUF Header Parsing βββββββββββββββββββββββββββββββββββββ++/**+ * Parse the header and metadata from a GGUF file without loading tensors.+ * Reads only the first 256 KB of the file.+ */+export async function parseGgufHeader(path: string): Promise<GgufMetadata> {+ const fileInfo = await fsStat(path);+ const readSize = Math.min(fileInfo.size, 256 * 1024);+ const fh = await open(path, 'r');+ try {+ const buf = Buffer.alloc(readSize);+ await fh.read(buf, 0, readSize, 0);+ return parseGgufBuffer(buf, fileInfo.size, path);+ } finally {+ await fh.close();+ }+}++function parseGgufBuffer(buf: Buffer, fileSize: number, filePath: string): GgufMetadata {+ const reader = new BufferReader(buf);++ const magic = reader.readU32();+ if (magic !== GGUF_MAGIC) {+ throw new Error(`Invalid GGUF magic: 0x${magic.toString(16)} (expected 0x${GGUF_MAGIC.toString(16)})`);+ }++ const version = reader.readU32();+ if (version < 2 || version > 3) {+ throw new Error(`Unsupported GGUF version: ${version} (expected 2 or 3)`);+ }++ const tensorCount = reader.readU64AsNumber();+ const kvCount = reader.readU64AsNumber();++ const metadata: Record<string, unknown> = {};+ for (let i = 0; i < kvCount; i++) {+ if (reader.remaining < 12) break;+ try {+ const key = reader.readString();+ metadata[key] = readGgufValue(reader);+ } catch {+ break; // reached end of read window+ }+ }++ const arch = asString(metadata['general.architecture']);+ const pfx = arch || 'llama'; // fallback prefix for well-known keys++ return {+ magic: 'GGUF', version, tensorCount, kvCount,+ architecture: arch,+ name: asString(metadata['general.name']),+ contextLength: asNumber(metadata[`${pfx}.context_length`]),+ embeddingLength: asNumber(metadata[`${pfx}.embedding_length`]),+ blockCount: asNumber(metadata[`${pfx}.block_count`]),+ vocabSize: inferVocabSize(metadata),+ quantization: inferQuantFromMetadata(metadata, filePath),+ fileSize, metadata,+ };+}++// ββ Metadata Helpers ββββββββββββββββββββββββββββββββββββββββ++function asString(v: unknown): string | undefined { return typeof v === 'string' ? v : undefined; }+function asNumber(v: unknown): number | undefined { return typeof v === 'number' ? v : undefined; }++const QUANT_RE: Array<[RegExp, string]> = [+ [/q2_k/i, 'Q2_K'], [/q3_k_s/i, 'Q3_K_S'], [/q3_k_m/i, 'Q3_K_M'], [/q3_k_l/i, 'Q3_K_L'],+ [/q4_k_s/i, 'Q4_K_S'], [/q4_k_m/i, 'Q4_K_M'], [/q4_0/i, 'Q4_0'], [/q4_1/i, 'Q4_1'],+ [/q5_k_s/i, 'Q5_K_S'], [/q5_k_m/i, 'Q5_K_M'], [/q5_0/i, 'Q5_0'], [/q5_1/i, 'Q5_1'],+ [/q6_k/i, 'Q6_K'], [/q8_0/i, 'Q8_0'], [/f16/i, 'F16'], [/f32/i, 'F32'],+];++function inferQuantFromMetadata(meta: Record<string, unknown>, filePath: string): string {+ const ft = meta['general.file_type'];+ if (typeof ft === 'number') return `file_type_${ft}`;+ const name = basename(filePath);+ for (const [re, label] of QUANT_RE) if (re.test(name)) return label;+ return 'unknown';+}++function inferVocabSize(meta: Record<string, unknown>): number | undefined {+ const tokens = meta['tokenizer.ggml.tokens'];+ if (Array.isArray(tokens)) return tokens.length;+ return asNumber(meta['tokenizer.ggml.vocab_size']);+}++// ββ GGUF Engine βββββββββββββββββββββββββββββββββββββββββββββ++export class GgufEngine {+ private config: Required<GgufEngineConfig>;+ private llamaCpp: any = null;+ private llamaModel: any = null;+ private llamaContext: any = null;+ private loadedModels: Map<string, GgufMetadata> = new Map();+ private activeModelPath: string | null = null;+ private kvCache: Map<string, Buffer> = new Map();++ constructor(config: GgufEngineConfig) {+ this.config = {+ contextSize: config.contextSize ?? 4096,+ maxTokens: config.maxTokens ?? 512,+ temperature: config.temperature ?? 0.7,+ kvCachePath: config.kvCachePath ?? '',+ verbose: config.verbose ?? false,+ };+ }++ /** Probe for node-llama-cpp availability. */+ async initialize(): Promise<void> {+ this.llamaCpp = await this.tryLoadLlamaCpp();+ if (this.config.verbose) {+ console.log(`[gguf-engine] node-llama-cpp: ${this.llamaCpp ? 'available' : 'not found (metadata-only mode)'}`);+ }+ }++ /** Parse GGUF header and optionally load the model for inference. */+ async loadModel(path: string): Promise<GgufMetadata> {+ const meta = await parseGgufHeader(path);+ this.loadedModels.set(path, meta);+ this.activeModelPath = path;++ if (this.llamaCpp) {+ try {+ const { getLlama } = this.llamaCpp;+ const llama = await getLlama();+ this.llamaModel = await llama.loadModel({ modelPath: path });+ this.llamaContext = await this.llamaModel.createContext({ contextSize: this.config.contextSize });+ if (this.config.verbose) console.log(`[gguf-engine] Model loaded: ${basename(path)}`);+ } catch (err) {+ if (this.config.verbose) console.warn('[gguf-engine] node-llama-cpp load failed:', err);+ this.llamaModel = null;+ this.llamaContext = null;+ }+ }+ return meta;+ }++ /** Generate text. Delegates to node-llama-cpp or returns a metadata-only stub. */+ async generate(request: GenerateRequest): Promise<GenerateResponse> {+ const start = performance.now();+ const modelPath = request.model ?? this.activeModelPath;+ const modelName = modelPath ? basename(modelPath) : 'none';++ if (this.llamaContext && this.llamaModel) {+ try {+ const session = new this.llamaCpp.LlamaChatSession({+ contextSequence: this.llamaContext.getSequence(),+ });+ const text = await session.prompt(request.prompt, {+ maxTokens: request.maxTokens ?? this.config.maxTokens,+ temperature: request.temperature ?? this.config.temperature,+ stopGenerationTrigger: request.stopSequences+ ? request.stopSequences.map((s: string) => new this.llamaCpp.LlamaText([s]))+ : undefined,+ });+ return {+ text, model: modelName, tokensUsed: text.split(/\s+/).length,+ latencyMs: performance.now() - start, metadataOnly: false,+ };+ } catch (err) {+ if (this.config.verbose) console.warn('[gguf-engine] Generation failed:', err);+ }+ }++ // Metadata-only fallback+ const meta = modelPath ? this.loadedModels.get(modelPath) : undefined;+ return {+ text: meta+ ? `[metadata-only] Model: ${meta.name ?? modelName}, arch: ${meta.architecture ?? 'unknown'}, ctx: ${meta.contextLength ?? 'unknown'}`+ : '[metadata-only] No model loaded',+ model: modelName, tokensUsed: 0,+ latencyMs: performance.now() - start, metadataOnly: true,+ };+ }++ /** Stream tokens via async iterator. Falls back to yielding full response. */+ async *stream(request: GenerateRequest): AsyncGenerator<string> {+ if (this.llamaContext && this.llamaModel) {+ try {+ const session = new this.llamaCpp.LlamaChatSession({+ contextSequence: this.llamaContext.getSequence(),+ });+ const it = session.promptWithMeta(request.prompt, {+ maxTokens: request.maxTokens ?? this.config.maxTokens,+ temperature: request.temperature ?? this.config.temperature,+ });+ if (it && typeof it[Symbol.asyncIterator] === 'function') {+ for await (const chunk of it) {+ if (typeof chunk === 'string') yield chunk;+ else if (chunk?.text) yield chunk.text;+ }+ return;+ }+ } catch { /* fall through to single-chunk fallback */ }+ }+ const response = await this.generate(request);+ yield response.text;+ }++ /**+ * Persist the KV cache to an RVF-compatible binary file.+ * Format: RVKV magic | version u32 | model SHA-256 (32B) | entry count u32+ * entries: [key_len u32, key, val_len u32, val] | footer SHA-256 (32B)+ */+ async persistKvCache(outputPath: string): Promise<void> {+ const path = outputPath || this.config.kvCachePath;+ if (!path) throw new Error('No KV cache output path specified');++ const modelHash = createHash('sha256').update(this.activeModelPath ?? 'no-model').digest();+ const entryBufs: Buffer[] = [];+ for (const [key, value] of this.kvCache) {+ const keyBuf = Buffer.from(key, 'utf-8');+ const hdr = Buffer.alloc(8);+ hdr.writeUInt32LE(keyBuf.length, 0);+ hdr.writeUInt32LE(value.length, 4);+ entryBufs.push(hdr, keyBuf, value);+ }+ const entryData = Buffer.concat(entryBufs);+ const footer = createHash('sha256').update(entryData).digest();++ const header = Buffer.alloc(44);+ header.writeUInt32LE(RVKV_MAGIC, 0);+ header.writeUInt32LE(RVKV_VERSION, 4);+ modelHash.copy(header, 8);+ header.writeUInt32LE(this.kvCache.size, 40);++ await writeFile(path, Buffer.concat([header, entryData, footer]));+ if (this.config.verbose) console.log(`[gguf-engine] KV cache persisted: ${this.kvCache.size} entries`);+ }++ /** Restore KV cache from an RVF-compatible binary file. */+ async loadKvCache(inputPath: string): Promise<void> {+ const data = await readFile(inputPath);+ if (data.length < 44) throw new Error('KV cache file too small');++ const magic = data.readUInt32LE(0);+ if (magic !== RVKV_MAGIC) throw new Error(`Invalid KV cache magic: 0x${magic.toString(16)}`);+ const version = data.readUInt32LE(4);+ if (version !== RVKV_VERSION) throw new Error(`Unsupported KV cache version: ${version}`);++ const entryCount = data.readUInt32LE(40);+ let offset = 44;+ const entries = new Map<string, Buffer>();++ for (let i = 0; i < entryCount; i++) {+ if (offset + 8 > data.length) throw new Error('KV cache file truncated');+ const keyLen = data.readUInt32LE(offset);+ const valLen = data.readUInt32LE(offset + 4);+ offset += 8;+ if (offset + keyLen + valLen > data.length) throw new Error('KV cache file truncated');+ entries.set(data.toString('utf-8', offset, offset + keyLen), Buffer.from(data.subarray(offset + keyLen, offset + keyLen + valLen)));+ offset += keyLen + valLen;+ }++ // Verify footer hash+ if (offset + 32 <= data.length) {+ const stored = data.subarray(offset, offset + 32);+ const computed = createHash('sha256').update(data.subarray(44, offset)).digest();+ if (!stored.equals(computed)) throw new Error('KV cache integrity check failed: hash mismatch');+ }++ this.kvCache = entries;+ if (this.config.verbose) console.log(`[gguf-engine] KV cache loaded: ${entries.size} entries`);+ }++ /** Return metadata for all loaded models. */+ getLoadedModels(): GgufMetadata[] { return Array.from(this.loadedModels.values()); }++ /** Store a key-value pair in the in-memory KV cache. */+ setKvEntry(key: string, value: Buffer): void { this.kvCache.set(key, value); }++ /** Retrieve a key-value pair from the in-memory KV cache. */+ getKvEntry(key: string): Buffer | undefined { return this.kvCache.get(key); }++ /** Release resources, unload models, and optionally persist the KV cache. */+ async shutdown(): Promise<void> {+ if (this.config.kvCachePath && this.kvCache.size > 0) {+ try { await this.persistKvCache(this.config.kvCachePath); }+ catch (err) { if (this.config.verbose) console.warn('[gguf-engine] KV persist failed:', err); }+ }+ if (this.llamaContext?.dispose) { try { await this.llamaContext.dispose(); } catch { /* ignore */ } }+ if (this.llamaModel?.dispose) { try { await this.llamaModel.dispose(); } catch { /* ignore */ } }+ this.llamaContext = null;+ this.llamaModel = null;+ this.activeModelPath = null;+ this.loadedModels.clear();+ this.kvCache.clear();+ if (this.config.verbose) console.log('[gguf-engine] Shutdown complete');+ }++ // ββ Private βββββββββββββββββββββββββββββββββββββββββββββββ++ private async tryLoadLlamaCpp(): Promise<any> {+ try { return await import('node-llama-cpp'); } catch { return null; }+ }+}diff --git a/v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts b/v3/@claude-flow/cli/src/appliance/ruvllm-bridge.tsindex 42d634e062..befaa25d64 100644--- a/v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts+++ b/v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts@@ -15,6 +15,7 @@import { readdir, stat } from 'node:fs/promises';import { join, extname, basename } from 'node:path';+import type { GgufEngine as GgufEngineType, GgufMetadata } from './gguf-engine.js';// ββ Configuration βββββββββββββββββββββββββββββββββββββββββββ@@ -128,17 +129,34 @@ export class RuvllmBridge {private ruvectorCore: any = null;private ruvectorRouter: any = null;private ruvectorSona: any = null;+ private ggufEngine: GgufEngineType | null = null;constructor(config: RuvllmConfig) {if (!config.modelsDir) throw new Error('RuvllmConfig.modelsDir is required');this.config = { ...DEFAULT_CONFIG, ...config };}- /** Probe optional @ruvector packages and scan modelsDir for GGUF files. */+ /** Probe optional @ruvector packages, initialize GGUF engine, and scan modelsDir. */async initialize(): Promise<void> {this.ruvectorCore = await this.tryImport('@ruvector/core');this.ruvectorRouter = await this.tryImport('@ruvector/router');this.ruvectorSona = await this.tryImport('@ruvector/sona');++ // Initialize GGUF engine for local model inference+ try {+ const { GgufEngine } = await import('./gguf-engine.js');+ this.ggufEngine = new GgufEngine({+ contextSize: this.config.contextSize,+ maxTokens: this.config.maxTokens,+ temperature: this.config.temperature,+ kvCachePath: this.config.kvCachePath,+ verbose: this.config.verbose,+ });+ await this.ggufEngine.initialize();+ } catch {+ // GGUF engine is optional+ }+await this.scanModelsDir();if (this.config.verbose) {@@ -146,6 +164,7 @@ export class RuvllmBridge {this.ruvectorCore && '@ruvector/core',this.ruvectorRouter && '@ruvector/router',this.ruvectorSona && '@ruvector/sona',+ this.ggufEngine && 'gguf-engine',].filter(Boolean);if (pkgs.length) console.log(`[ruvLLM] Loaded: ${pkgs.join(', ')}`);console.log(`[ruvLLM] ${this.models.size} model(s) in ${this.config.modelsDir}`);@@ -157,12 +176,17 @@ export class RuvllmBridge {return Array.from(this.models.values());}- /** Load a model into memory (delegates to @ruvector/core when available). */+ /** Load a model into memory (delegates to GGUF engine or @ruvector/core). */async loadModel(name: string): Promise<void> {const info = this.models.get(name);if (!info) throw new Error(`Model "${name}" not found. Available: ${[...this.models.keys()].join(', ')}`);- if (this.ruvectorCore?.loadModel) {+ // Prefer GGUF engine (parses header, loads via node-llama-cpp if available)+ if (this.ggufEngine) {+ const meta = await this.ggufEngine.loadModel(info.path);+ if (meta.architecture) info.parameters = meta.architecture;+ if (meta.quantization) info.quantization = meta.quantization;+ } else if (this.ruvectorCore?.loadModel) {await this.ruvectorCore.loadModel(info.path, { contextSize: this.config.contextSize });}info.loaded = true;@@ -185,17 +209,27 @@ export class RuvllmBridge {return { text: booster, model: 'agent-booster', tokensUsed: 0, latencyMs: performance.now() - start, tier: 1, cached: false };}- // Tier 2: Local model+ // Tier 2: Local model (GGUF engine preferred, then @ruvector/core)const info = this.models.get(modelName);- if (info?.loaded && this.ruvectorCore?.generate) {+ if (info?.loaded) {try {- const r = await this.ruvectorCore.generate({- model: info.path, prompt: request.prompt,- maxTokens: request.maxTokens ?? this.config.maxTokens,- temperature: request.temperature ?? this.config.temperature,- stopSequences: request.stopSequences,- });- return { text: r.text ?? '', model: modelName, tokensUsed: r.tokensUsed ?? 0, latencyMs: performance.now() - start, tier: 2, cached: false };+ if (this.ggufEngine) {+ const r = await this.ggufEngine.generate({+ prompt: request.prompt,+ maxTokens: request.maxTokens ?? this.config.maxTokens,+ temperature: request.temperature ?? this.config.temperature,+ stopSequences: request.stopSequences,+ });+ return { text: r.text, model: modelName, tokensUsed: r.tokensUsed, latencyMs: performance.now() - start, tier: 2, cached: false };+ } else if (this.ruvectorCore?.generate) {+ const r = await this.ruvectorCore.generate({+ model: info.path, prompt: request.prompt,+ maxTokens: request.maxTokens ?? this.config.maxTokens,+ temperature: request.temperature ?? this.config.temperature,+ stopSequences: request.stopSequences,+ });+ return { text: r.text ?? '', model: modelName, tokensUsed: r.tokensUsed ?? 0, latencyMs: performance.now() - start, tier: 2, cached: false };+ }} catch (err) {if (this.config.verbose) console.warn('[ruvLLM] Local generation failed, tier 3 fallback:', err);}@@ -236,6 +270,10 @@ export class RuvllmBridge {/** Persist KV-cache, unload models, and clean up. */async shutdown(): Promise<void> {+ if (this.ggufEngine) {+ await this.ggufEngine.shutdown();+ this.ggufEngine = null;+ }if (this.config.kvCachePath && this.ruvectorCore?.persistKvCache) {try { await this.ruvectorCore.persistKvCache(this.config.kvCachePath); }catch (e) { if (this.config.verbose) console.warn('[ruvLLM] KV-cache persist failed:', e); }diff --git a/v3/@claude-flow/cli/src/appliance/rvfa-distribution.ts b/v3/@claude-flow/cli/src/appliance/rvfa-distribution.tsnew file mode 100644index 0000000000..87b0c13ffa--- /dev/null+++ b/v3/@claude-flow/cli/src/appliance/rvfa-distribution.ts@@ -0,0 +1,376 @@+/**+ * RVFA Distribution & Hot-Patch Module+ *+ * IPFS publishing of RVFA appliances via Pinata and RVFP binary patches+ * for section-level hot updates with atomic rollback.+ *+ * RVFP layout: [4B "RVFP"] [4B version u32LE] [4B header_len u32LE]+ * [header JSON] [new section data] [32B SHA256 footer]+ */++import { createHash, sign, verify as edVerify } from 'node:crypto';+import { readFile, writeFile, rename, unlink, copyFile, mkdir } from 'node:fs/promises';+import { dirname } from 'node:path';+import { request as httpsRequest } from 'node:https';+import { gzipSync, gunzipSync } from 'node:zlib';+import { RvfaReader, RvfaWriter } from './rvfa-format.js';++// ββ Constants ββββββββββββββββββββββββββββββββββββββββββββββββ+const RVFP_VERSION = 1;+const PRE = 12; // preamble: 4 magic + 4 version + 4 header_len+const SHA_LEN = 32;+const DEFAULT_GW = 'https://gateway.pinata.cloud';+const DEFAULT_API = 'https://api.pinata.cloud';++// ββ Types ββββββββββββββββββββββββββββββββββββββββββββββββββββ+export interface RvfpHeader {+ magic: 'RVFP'; version: number;+ targetApplianceName: string; targetApplianceVersion: string;+ targetSection: string; patchVersion: string; created: string;+ newSectionSize: number; newSectionSha256: string;+ compression: 'none' | 'gzip'; signature?: string; signedBy?: string;+}+export interface CreatePatchOptions {+ targetName: string; targetVersion: string; sectionId: string;+ sectionData: Buffer; patchVersion: string;+ compression?: 'none' | 'gzip'; privateKey?: Buffer; signedBy?: string;+}+export interface ApplyOptions { backup?: boolean; verify?: boolean; publicKey?: Buffer }+export interface ApplyResult {+ success: boolean; backupPath?: string; newSize: number;+ patchedSection: string; errors: string[];+}+export interface PatchVerifyResult { valid: boolean; header: RvfpHeader; errors: string[] }+export interface PublishConfig { pinataJwt?: string; gatewayUrl?: string; apiUrl?: string }+export interface PublishMetadata { name?: string; description?: string; version?: string; profile?: string }+export interface PublishResult { cid: string; size: number; gatewayUrl: string; pinataUrl: string }+export interface PublishedItem { cid: string; name: string; size: number; date: string }++// ββ Crypto helpers βββββββββββββββββββββββββββββββββββββββββββ+function sha256(d: Buffer): string { return createHash('sha256').update(d).digest('hex'); }+function sha256B(d: Buffer): Buffer { return createHash('sha256').update(d).digest(); }++function edSign(data: Buffer, key: Buffer): string {+ return sign(null, data, { key, format: 'der', type: 'pkcs8' }).toString('hex');+}+function edCheck(data: Buffer, sig: string, key: Buffer): boolean {+ try {+ return edVerify(null, data, { key, format: 'der', type: 'spki' }, Buffer.from(sig, 'hex'));+ } catch { return false; }+}++// ββ HTTP helpers βββββββββββββββββββββββββββββββββββββββββββββ+function pinataReq(+ method: string, path: string, jwt: string, body?: Buffer, ct?: string,+): Promise<{ status: number; data: unknown }> {+ return new Promise((resolve, reject) => {+ const u = new URL(path);+ const h: Record<string, string> = { Authorization: `Bearer ${jwt}` };+ if (ct) h['Content-Type'] = ct;+ if (body) h['Content-Length'] = String(body.length);+ const req = httpsRequest(+ { hostname: u.hostname, path: u.pathname + u.search, method, headers: h },+ (res) => {+ const ch: Buffer[] = [];+ res.on('data', (c: Buffer) => ch.push(c));+ res.on('end', () => {+ const raw = Buffer.concat(ch);+ let data: unknown;+ try { data = JSON.parse(raw.toString('utf-8')); } catch { data = raw; }+ resolve({ status: res.statusCode ?? 0, data });+ });+ },+ );+ req.on('error', reject);+ if (body) req.write(body);+ req.end();+ });+}++function httpGet(url: string): Promise<Buffer> {+ return new Promise((resolve, reject) => {+ const u = new URL(url);+ httpsRequest({ hostname: u.hostname, path: u.pathname + u.search, method: 'GET' }, (res) => {+ if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {+ return void httpGet(res.headers.location).then(resolve, reject);+ }+ const ch: Buffer[] = [];+ res.on('data', (c: Buffer) => ch.push(c));+ res.on('end', () => resolve(Buffer.concat(ch)));+ }).on('error', reject).end();+ });+}++function multipart(+ name: string, file: string, data: Buffer, meta?: string,+): { body: Buffer; ct: string } {+ const b = `----Rvfa${Date.now()}${Math.random().toString(36).slice(2)}`;+ const parts: Buffer[] = [];+ if (meta) {+ parts.push(Buffer.from(+ `--${b}\r\nContent-Disposition: form-data; name="pinataMetadata"\r\n` ++ `Content-Type: application/json\r\n\r\n${meta}\r\n`,+ ));+ }+ parts.push(Buffer.from(+ `--${b}\r\nContent-Disposition: form-data; name="${name}"; filename="${file}"\r\n` ++ `Content-Type: application/octet-stream\r\n\r\n`,+ ));+ parts.push(data, Buffer.from(`\r\n--${b}--\r\n`));+ return { body: Buffer.concat(parts), ct: `multipart/form-data; boundary=${b}` };+}++/** Extract patch section data and bounds from a parsed patch buffer. */+function patchData(buf: Buffer): { start: number; end: number; section: Buffer } {+ const hLen = buf.readUInt32LE(8);+ const start = PRE + hLen;+ const end = buf.length - SHA_LEN;+ return { start, end, section: buf.subarray(start, end) };+}++/** Build a failed ApplyResult. */+function failResult(sec: string, errs: string[], extra?: Partial<ApplyResult>): ApplyResult {+ return { success: false, newSize: 0, patchedSection: sec, errors: errs, ...extra };+}++// ββ RvfaPatcher ββββββββββββββββββββββββββββββββββββββββββββββ+export class RvfaPatcher {+ static async createPatch(opts: CreatePatchOptions): Promise<Buffer> {+ const comp = opts.compression ?? 'none';+ const payload = comp === 'gzip' ? gzipSync(opts.sectionData) : opts.sectionData;+ const header: RvfpHeader = {+ magic: 'RVFP', version: RVFP_VERSION,+ targetApplianceName: opts.targetName, targetApplianceVersion: opts.targetVersion,+ targetSection: opts.sectionId, patchVersion: opts.patchVersion,+ created: new Date().toISOString(), newSectionSize: payload.length,+ newSectionSha256: sha256(payload), compression: comp,+ };+ if (opts.privateKey && opts.signedBy) {+ const signable = Buffer.concat([Buffer.from(JSON.stringify(header), 'utf-8'), payload]);+ header.signature = edSign(signable, opts.privateKey);+ 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 };+ }+ if (section.length !== header.newSectionSize)+ errors.push(`Size mismatch: header=${header.newSectionSize}, actual=${section.length}`);+ if (sha256(section) !== header.newSectionSha256)+ errors.push('Section SHA256 mismatch');+ if (!sha256B(section).equals(buf.subarray(buf.length - SHA_LEN)))+ errors.push('Footer SHA256 mismatch');+ return { valid: errors.length === 0, header, errors };+ }++ static async applyPatch(+ rvfaPath: string, patchBuf: Buffer, opts?: ApplyOptions,+ ): Promise<ApplyResult> {+ const doBackup = opts?.backup ?? true;+ const doVerify = opts?.verify ?? true;++ // Parse & verify patch+ let header: RvfpHeader;+ try { header = RvfaPatcher.parsePatchHeader(patchBuf); } catch (e) {+ return failResult('', [(e as Error).message]);+ }+ const sec = header.targetSection;++ // Verify signature+ if (opts?.publicKey && header.signature) {+ const { section } = patchData(patchBuf);+ const unsigned = { ...header } as Record<string, unknown>;+ delete unsigned.signature; delete unsigned.signedBy;+ const signable = Buffer.concat([Buffer.from(JSON.stringify(unsigned), 'utf-8'), section]);+ if (!edCheck(signable, header.signature, opts.publicKey))+ return failResult(sec, ['Patch signature verification failed']);+ }++ // Verify patch integrity+ const check = await RvfaPatcher.verifyPatch(patchBuf);+ if (!check.valid) return failResult(sec, check.errors);++ // Read target RVFA+ let reader: RvfaReader;+ try { reader = await RvfaReader.fromFile(rvfaPath); } catch (e) {+ return failResult(sec, [`Failed to read RVFA: ${(e as Error).message}`]);+ }+ const rh = reader.getHeader();++ // Verify target matches+ const errs: string[] = [];+ if (rh.name !== header.targetApplianceName)+ errs.push(`Name mismatch: patch="${header.targetApplianceName}", file="${rh.name}"`);+ if (rh.appVersion !== header.targetApplianceVersion)+ errs.push(`Version mismatch: patch="${header.targetApplianceVersion}", file="${rh.appVersion}"`);+ if (errs.length) return failResult(sec, errs);+ if (!rh.sections.find((s) => s.id === sec))+ return failResult(sec, [`Section "${sec}" not found in appliance`]);++ // Backup+ let backupPath: string | undefined;+ if (doBackup) { backupPath = rvfaPath + '.bak'; await copyFile(rvfaPath, backupPath); }++ // Extract new section data from patch (decompress if needed)+ let newData = patchData(patchBuf).section;+ if (header.compression === 'gzip') newData = gunzipSync(newData);++ // Rebuild RVFA with replaced section+ const writer = new RvfaWriter({ ...rh, sections: [] });+ for (const s of rh.sections) {+ const comp = s.compression === 'zstd' ? 'gzip' : s.compression;+ if (s.id === sec) {+ writer.addSection(s.id, newData, { compression: comp, type: s.type });+ } else {+ writer.addSection(s.id, reader.extractSection(s.id), { compression: comp, type: s.type });+ }+ }+ const newRvfa = writer.build();++ // Atomic write (tmp + rename)+ const tmpPath = rvfaPath + `.tmp.${Date.now()}`;+ try {+ await writeFile(tmpPath, newRvfa);+ await rename(tmpPath, rvfaPath);+ } catch (e) {+ await unlink(tmpPath).catch(() => {});+ if (backupPath) await copyFile(backupPath, rvfaPath).catch(() => {});+ return failResult(sec, [`Atomic write failed: ${(e as Error).message}`], { backupPath });+ }++ // Post-patch verification with rollback+ if (doVerify) {+ try {+ const vr = await RvfaReader.fromFile(rvfaPath);+ const vResult = vr.verify();+ if (!vResult.valid) {+ if (backupPath) await copyFile(backupPath, rvfaPath).catch(() => {});+ return failResult(sec, [`Post-patch verification failed: ${vResult.errors.join('; ')}`],+ { backupPath, newSize: newRvfa.length });+ }+ } catch (e) {+ if (backupPath) await copyFile(backupPath, rvfaPath).catch(() => {});+ return failResult(sec, [`Post-patch verify error: ${(e as Error).message}`],+ { backupPath, newSize: newRvfa.length });+ }+ }++ return { success: true, backupPath, newSize: newRvfa.length, patchedSection: sec, errors: [] };+ }+}++// ββ RvfaPublisher ββββββββββββββββββββββββββββββββββββββββββββ+export class RvfaPublisher {+ private jwt: string;+ private gw: string;+ private api: string;++ constructor(config: PublishConfig) {+ this.jwt = config.pinataJwt || process.env.PINATA_API_JWT || '';+ this.gw = (config.gatewayUrl || DEFAULT_GW).replace(/\/+$/, '');+ this.api = (config.apiUrl || DEFAULT_API).replace(/\/+$/, '');+ if (!this.jwt) throw new Error('Pinata JWT required (config.pinataJwt or PINATA_API_JWT)');+ }++ private async upload(+ fileName: string, data: Buffer, kv: Record<string, string>,+ ): Promise<PublishResult> {+ const meta = JSON.stringify({ name: fileName, keyvalues: kv });+ const { body, ct } = multipart('file', fileName, data, meta);+ const res = await pinataReq('POST', `${this.api}/pinning/pinFileToIPFS`, this.jwt, body, ct);+ if (res.status !== 200)+ throw new Error(`Pinata upload failed (HTTP ${res.status}): ${JSON.stringify(res.data)}`);+ const r = res.data as { IpfsHash: string; PinSize: number };+ return {+ cid: r.IpfsHash, size: r.PinSize,+ gatewayUrl: `${this.gw}/ipfs/${r.IpfsHash}`, pinataUrl: `${this.api}/pinning/pins/${r.IpfsHash}`,+ };+ }++ async publish(rvfaPath: string, meta?: PublishMetadata): Promise<PublishResult> {+ const data = await readFile(rvfaPath);+ const name = meta?.name || rvfaPath.split('/').pop() || 'appliance.rvf';+ return this.upload(name, data, {+ type: 'rvfa-appliance', version: meta?.version || '',+ profile: meta?.profile || '', description: meta?.description || '',+ });+ }++ async publishPatch(patchBuf: Buffer, meta?: PublishMetadata): Promise<PublishResult> {+ const name = meta?.name || `patch-${Date.now()}.rvfp`;+ return this.upload(name, patchBuf, {+ type: 'rvfp-patch', version: meta?.version || '', description: meta?.description || '',+ });+ }++ async fetch(cid: string, outputPath: string): Promise<void> {+ const data = await httpGet(`${this.gw}/ipfs/${cid}`);+ await mkdir(dirname(outputPath), { recursive: true });+ await writeFile(outputPath, data);+ }++ async list(): Promise<PublishedItem[]> {+ const res = await pinataReq('GET', `${this.api}/data/pinList?status=pinned&pageLimit=100`, this.jwt);+ if (res.status !== 200)+ throw new Error(`Pinata list failed (HTTP ${res.status}): ${JSON.stringify(res.data)}`);+ const d = res.data as { rows: Array<{+ ipfs_pin_hash: string; metadata?: { name?: string }; size: number; date_pinned: string;+ }> };+ return (d.rows || []).map((r) => ({+ cid: r.ipfs_pin_hash, name: r.metadata?.name || r.ipfs_pin_hash,+ size: r.size, date: r.date_pinned,+ }));+ }++ async pin(cid: string, name?: string): Promise<void> {+ const body = Buffer.from(JSON.stringify({ hashToPin: cid, pinataMetadata: { name: name || cid } }));+ const res = await pinataReq('POST', `${this.api}/pinning/pinByHash`, this.jwt, body, 'application/json');+ if (res.status !== 200)+ throw new Error(`Pinata pin failed (HTTP ${res.status}): ${JSON.stringify(res.data)}`);+ }+}++// ββ Convenience exports ββββββββββββββββββββββββββββββββββββββ+export function createPublisher(config?: Partial<PublishConfig>): RvfaPublisher {+ return new RvfaPublisher({ pinataJwt: config?.pinataJwt, gatewayUrl: config?.gatewayUrl, apiUrl: config?.apiUrl });+}++export async function createAndVerifyPatch(+ options: CreatePatchOptions,+): Promise<{ patch: Buffer; verification: PatchVerifyResult }> {+ const patch = await RvfaPatcher.createPatch(options);+ const verification = await RvfaPatcher.verifyPatch(patch);+ return { patch, verification };+}diff --git a/v3/@claude-flow/cli/src/appliance/rvfa-signing.ts b/v3/@claude-flow/cli/src/appliance/rvfa-signing.tsnew file mode 100644index 0000000000..46cc2c88ff--- /dev/null+++ b/v3/@claude-flow/cli/src/appliance/rvfa-signing.ts@@ -0,0 +1,458 @@+/**+ * RVFA Ed25519 Code Signing -- Digital signatures for RVFA appliance files.+ *+ * Provides tamper detection and publisher identity verification using+ * Ed25519 (RFC 8032) via Node.js native crypto. Zero external dependencies.+ *+ * @module @claude-flow/cli/appliance/rvfa-signing+ */++import {+ generateKeyPairSync, createHash, sign, verify,+ createPublicKey, createPrivateKey,+ type KeyObject,+} from 'node:crypto';+import { readFile, writeFile, stat, chmod } from 'node:fs/promises';++// ββ Constants ββββββββββββββββββββββββββββββββββββββββββββββββ++const PREAMBLE_SIZE = 12; // 4B magic + 4B version + 4B header_len+const SHA256_SIZE = 32;+const KEY_FILE_MODE = 0o600;++// ββ Public Interfaces ββββββββββββββββββββββββββββββββββββββββ++export interface RvfaKeyPair {+ publicKey: Buffer;+ privateKey: Buffer;+ fingerprint: string;+}++export interface SignatureMetadata {+ algorithm: 'ed25519';+ publicKeyFingerprint: string;+ signature: string;+ signedAt: string;+ signedBy?: string;+ scope: 'full' | 'sections';+}++export interface VerifyResult {+ valid: boolean;+ signerFingerprint?: string;+ signedAt?: string;+ signedBy?: string;+ errors: string[];+}++// ββ Key Management βββββββββββββββββββββββββββββββββββββββββββ++/** Compute the fingerprint of a public key: first 16 hex chars of its SHA256. */+function computeFingerprint(publicKeyPem: string): string {+ return createHash('sha256')+ .update(publicKeyPem, 'utf-8')+ .digest('hex')+ .slice(0, 16);+}++/**+ * Generate a new Ed25519 key pair for RVFA signing.+ */+export async function generateKeyPair(): Promise<RvfaKeyPair> {+ const { publicKey, privateKey } = generateKeyPairSync('ed25519', {+ publicKeyEncoding: { type: 'spki', format: 'pem' },+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },+ });++ const pubBuf = Buffer.from(publicKey as string, 'utf-8');+ const privBuf = Buffer.from(privateKey as string, 'utf-8');+ const fingerprint = computeFingerprint(publicKey as string);++ return { publicKey: pubBuf, privateKey: privBuf, fingerprint };+}++/**+ * Save a key pair to disk as PEM files.+ *+ * @param keyPair The key pair to persist.+ * @param dir Directory to write files into.+ * @param name Base name for the key files (default: 'rvfa-signing').+ * @returns Paths to the written public and private key files.+ */+export async function saveKeyPair(+ keyPair: RvfaKeyPair,+ dir: string,+ name = 'rvfa-signing',+): Promise<{ publicKeyPath: string; privateKeyPath: string }> {+ const pubPath = `${dir}/${name}.pub`;+ const privPath = `${dir}/${name}.key`;++ await writeFile(pubPath, keyPair.publicKey);+ await writeFile(privPath, keyPair.privateKey, { mode: KEY_FILE_MODE });++ // Ensure private key has restrictive permissions even on existing files+ await chmod(privPath, KEY_FILE_MODE);++ return { publicKeyPath: pubPath, privateKeyPath: privPath };+}++/**+ * Load a key pair from PEM files on disk.+ *+ * @param dir Directory containing the key files.+ * @param name Base name for the key files (default: 'rvfa-signing').+ */+export async function loadKeyPair(+ dir: string,+ name = 'rvfa-signing',+): Promise<RvfaKeyPair> {+ const pubPath = `${dir}/${name}.pub`;+ const privPath = `${dir}/${name}.key`;++ const publicKey = await readFile(pubPath);+ const privateKey = await readFile(privPath);++ // Warn if private key permissions are too open+ const privStat = await stat(privPath);+ const mode = privStat.mode & 0o777;+ if (mode & 0o077) {+ console.warn(+ `[rvfa-signing] WARNING: Private key ${privPath} has open permissions ` ++ `(${mode.toString(8)}). Consider running: chmod 600 ${privPath}`,+ );+ }++ const fingerprint = computeFingerprint(publicKey.toString('utf-8'));+ return { publicKey, privateKey, fingerprint };+}++/**+ * Load a public key from a single PEM file.+ */+export async function loadPublicKey(path: string): Promise<Buffer> {+ return readFile(path);+}++// ββ Internal Helpers βββββββββββββββββββββββββββββββββββββββββ++/**+ * Recursively sort object keys for canonical JSON serialization.+ * Produces deterministic output regardless of insertion order.+ */+function canonicalJson(value: unknown): string {+ return JSON.stringify(value, (_key, val) => {+ if (val !== null && typeof val === 'object' && !Array.isArray(val) && !Buffer.isBuffer(val)) {+ const sorted: Record<string, unknown> = {};+ for (const k of Object.keys(val as Record<string, unknown>).sort()) {+ sorted[k] = (val as Record<string, unknown>)[k];+ }+ return sorted;+ }+ return val;+ });+}++/**+ * Parse an RVFA binary into its components without full validation.+ * Returns the header object, header JSON bytes, section data region, and footer.+ */+function parseRvfaBinary(buf: Buffer): {+ header: Record<string, unknown>;+ headerStart: number;+ headerEnd: number;+ sectionData: Buffer;+ footer: Buffer;+} {+ if (buf.length < PREAMBLE_SIZE + SHA256_SIZE) {+ throw new Error('Buffer too small to be a valid RVFA file');+ }++ const magic = buf.subarray(0, 4).toString('ascii');+ if (magic !== 'RVFA') {+ throw new Error(`Invalid RVFA magic: expected "RVFA", got "${magic}"`);+ }++ const headerLen = buf.readUInt32LE(8);+ const headerStart = PREAMBLE_SIZE;+ const headerEnd = headerStart + headerLen;++ if (headerEnd > buf.length - SHA256_SIZE) {+ throw new Error('Header length extends beyond buffer');+ }++ const headerJson = buf.subarray(headerStart, headerEnd).toString('utf-8');+ let header: Record<string, unknown>;+ try {+ header = JSON.parse(headerJson) as Record<string, unknown>;+ } catch {+ throw new Error('Failed to parse RVFA header JSON');+ }++ const footer = buf.subarray(buf.length - SHA256_SIZE);+ const sectionData = buf.subarray(headerEnd, buf.length - SHA256_SIZE);++ return { header, headerStart, headerEnd, sectionData, footer };+}++/**+ * Compute the signing digest for an RVFA file.+ *+ * The digest is SHA256 of: canonical_header_json (without signature field)+ * + section_data_bytes+ * + footer_32_bytes+ */+function computeSigningDigest(+ header: Record<string, unknown>,+ sectionData: Buffer,+ footer: Buffer,+): Buffer {+ // Strip signature field from header for digest computation+ const stripped = { ...header };+ delete stripped.signature;++ const canonical = Buffer.from(canonicalJson(stripped), 'utf-8');++ return createHash('sha256')+ .update(canonical)+ .update(sectionData)+ .update(footer)+ .digest();+}++/** Convert a Buffer or PEM string into a KeyObject. */+function toPrivateKeyObject(key: Buffer | string): KeyObject {+ const pem = Buffer.isBuffer(key) ? key.toString('utf-8') : key;+ return createPrivateKey(pem);+}++/** Convert a Buffer or PEM string into a KeyObject. */+function toPublicKeyObject(key: Buffer | string): KeyObject {+ const pem = Buffer.isBuffer(key) ? key.toString('utf-8') : key;+ return createPublicKey(pem);+}++/**+ * Rebuild the RVFA binary with an updated header.+ *+ * Preserves the original preamble version, recalculates header length,+ * and keeps section data and footer intact.+ */+function rebuildRvfa(+ originalBuf: Buffer,+ newHeader: Record<string, unknown>,+ sectionData: Buffer,+ footer: Buffer,+): Buffer {+ const headerJson = Buffer.from(JSON.stringify(newHeader), 'utf-8');++ // Preamble: magic + version + new header length+ const preamble = Buffer.alloc(PREAMBLE_SIZE);+ originalBuf.copy(preamble, 0, 0, 8); // magic + version unchanged+ preamble.writeUInt32LE(headerJson.length, 8);++ return Buffer.concat([preamble, headerJson, sectionData, footer]);+}++// ββ RvfaSigner βββββββββββββββββββββββββββββββββββββββββββββββ++/**+ * Signs RVFA appliance files and data with Ed25519.+ */+export class RvfaSigner {+ private readonly keyObj: KeyObject;+ private readonly fingerprint: string;++ constructor(privateKey: Buffer | string) {+ this.keyObj = toPrivateKeyObject(privateKey);++ // Derive public key to compute fingerprint+ const pubPem = createPublicKey(this.keyObj)+ .export({ type: 'spki', format: 'pem' }) as string;+ this.fingerprint = computeFingerprint(pubPem);+ }++ /**+ * Sign an RVFA appliance file in-place.+ *+ * Algorithm:+ * 1. Read and parse the RVFA binary+ * 2. Strip any existing signature from the header+ * 3. Compute SHA256 of [canonical_header + section_data + footer]+ * 4. Sign the digest with Ed25519+ * 5. Embed signature metadata into the header+ * 6. Write the updated binary back to the file+ *+ * @param rvfaPath Path to the .rvf appliance file.+ * @param signedBy Optional publisher name.+ * @returns The signature metadata that was embedded.+ */+ async signAppliance(rvfaPath: string, signedBy?: string): Promise<SignatureMetadata> {+ const buf = await readFile(rvfaPath);+ const { header, sectionData, footer } = parseRvfaBinary(buf);++ // Compute digest over header (without signature) + sections + footer+ const digest = computeSigningDigest(header, sectionData, footer);++ // Ed25519 sign+ const sig = sign(null, digest, this.keyObj);++ const metadata: SignatureMetadata = {+ algorithm: 'ed25519',+ publicKeyFingerprint: this.fingerprint,+ signature: sig.toString('hex'),+ signedAt: new Date().toISOString(),+ signedBy,+ scope: 'full',+ };++ // Embed signature in header and rebuild+ header.signature = metadata;+ const rebuilt = rebuildRvfa(buf, header, sectionData, footer);+ await writeFile(rvfaPath, rebuilt);++ return metadata;+ }++ /**+ * Sign a section footer hash (detached signature).+ *+ * @param footerHash The 32-byte SHA256 footer hash from an RVFA file.+ * @returns Hex-encoded Ed25519 signature.+ */+ async signSections(footerHash: Buffer): Promise<string> {+ if (footerHash.length !== SHA256_SIZE) {+ throw new Error(+ `Footer hash must be ${SHA256_SIZE} bytes, got ${footerHash.length}`,+ );+ }+ const sig = sign(null, footerHash, this.keyObj);+ return sig.toString('hex');+ }++ /**+ * Sign an RVFP patch file (detached signature).+ *+ * @param patchData The raw patch binary data.+ * @returns Hex-encoded Ed25519 signature.+ */+ async signPatch(patchData: Buffer): Promise<string> {+ const digest = createHash('sha256').update(patchData).digest();+ const sig = sign(null, digest, this.keyObj);+ return sig.toString('hex');+ }+}++// ββ RvfaVerifier βββββββββββββββββββββββββββββββββββββββββββββ++/**+ * Verifies Ed25519 signatures on RVFA appliance files and data.+ */+export class RvfaVerifier {+ private readonly keyObj: KeyObject;+ private readonly fingerprint: string;++ constructor(publicKey: Buffer | string) {+ this.keyObj = toPublicKeyObject(publicKey);+ const pem = Buffer.isBuffer(publicKey) ? publicKey.toString('utf-8') : publicKey;+ this.fingerprint = computeFingerprint(pem);+ }++ /**+ * Verify the Ed25519 signature embedded in an RVFA appliance file.+ *+ * @param rvfaPath Path to the .rvf appliance file.+ * @returns Verification result with details and any errors.+ */+ async verifyAppliance(rvfaPath: string): Promise<VerifyResult> {+ const errors: string[] = [];++ let buf: Buffer;+ try {+ buf = await readFile(rvfaPath);+ } catch (err) {+ return { valid: false, errors: [`Failed to read file: ${(err as Error).message}`] };+ }++ let parsed: ReturnType<typeof parseRvfaBinary>;+ try {+ parsed = parseRvfaBinary(buf);+ } catch (err) {+ return { valid: false, errors: [`Invalid RVFA file: ${(err as Error).message}`] };+ }++ const { header, sectionData, footer } = parsed;++ // Extract signature metadata from header+ const sigRaw = header.signature;+ if (!sigRaw || typeof sigRaw !== 'object') {+ return { valid: false, errors: ['No signature found in RVFA header'] };+ }++ const sigMeta = sigRaw as Record<string, unknown>;+ if (sigMeta.algorithm !== 'ed25519') {+ errors.push(`Unsupported algorithm: ${String(sigMeta.algorithm)}`);+ return { valid: false, errors };+ }++ if (typeof sigMeta.signature !== 'string' || !sigMeta.signature) {+ errors.push('Signature field is missing or empty');+ return { valid: false, errors };+ }++ // Recompute the digest the same way the signer did+ const digest = computeSigningDigest(header, sectionData, footer);++ // Verify+ let sigBuf: Buffer;+ try {+ sigBuf = Buffer.from(sigMeta.signature as string, 'hex');+ } catch {+ errors.push('Signature is not valid hex');+ return { valid: false, errors };+ }++ let valid: boolean;+ try {+ valid = verify(null, digest, this.keyObj, sigBuf);+ } catch (err) {+ errors.push(`Verification error: ${(err as Error).message}`);+ return { valid: false, errors };+ }++ if (!valid) {+ errors.push('Ed25519 signature verification failed: data may be tampered');+ }++ return {+ valid,+ signerFingerprint: sigMeta.publicKeyFingerprint as string | undefined,+ signedAt: sigMeta.signedAt as string | undefined,+ signedBy: sigMeta.signedBy as string | undefined,+ errors,+ };+ }++ /**+ * Verify a detached Ed25519 signature over arbitrary data.+ *+ * @param data The data that was signed.+ * @param signature Hex-encoded Ed25519 signature.+ */+ async verifyDetached(data: Buffer, signature: string): Promise<boolean> {+ const digest = createHash('sha256').update(data).digest();+ const sigBuf = Buffer.from(signature, 'hex');+ return verify(null, digest, this.keyObj, sigBuf);+ }++ /**+ * Verify an RVFP patch file signature.+ *+ * @param patchData The raw patch binary data.+ * @param signature Hex-encoded Ed25519 signature.+ */+ async verifyPatch(patchData: Buffer, signature: string): Promise<boolean> {+ const digest = createHash('sha256').update(patchData).digest();+ const sigBuf = Buffer.from(signature, 'hex');+ return verify(null, digest, this.keyObj, sigBuf);+ }+}diff --git a/v3/@claude-flow/cli/src/commands/appliance-advanced.ts b/v3/@claude-flow/cli/src/commands/appliance-advanced.tsnew file mode 100644index 0000000000..b7ceaf2d9e--- /dev/null+++ b/v3/@claude-flow/cli/src/commands/appliance-advanced.ts@@ -0,0 +1,219 @@+/**+ * V3 CLI Appliance Advanced Commands (Phase 3-4)+ * Sign, publish, and hot-patch RVFA appliances.+ */++import type { Command, CommandContext, CommandResult } from '../types.js';+import { output } from '../output.js';++function fmtSize(bytes: number): string {+ if (bytes < 1024) return `${bytes} B`;+ if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;+ if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;+ return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;+}++function errMsg(err: unknown): string {+ return err instanceof Error ? err.message : String(err);+}++const fail = (msg: string, detail?: string): CommandResult => {+ output.printError(msg, detail);+ return { success: false, exitCode: 1 };+};++function hdr(title: string): void {+ output.writeln();+ output.writeln(output.bold(title));+ output.writeln(output.dim('β'.repeat(50)));+ output.writeln();+}++async function requireFile(file: string): Promise<boolean> {+ const fs = await import('fs');+ if (!fs.existsSync(file)) {+ output.printError(`File not found: ${file}`);+ return false;+ }+ return true;+}++// SIGN+export const signCommand: Command = {+ name: 'sign',+ description: 'Sign an RVFA appliance with Ed25519 for tamper detection',+ options: [+ { name: 'file', short: 'f', type: 'string', description: 'Path to .rvf file', required: true },+ { name: 'key', short: 'k', type: 'string', description: 'Path to Ed25519 private key (PEM)' },+ { name: 'generate-keys', type: 'boolean', description: 'Generate a new key pair' },+ { name: 'key-dir', type: 'string', description: 'Directory for key storage', default: '.rvfa-keys' },+ { name: 'signer', type: 'string', description: 'Publisher name for signature metadata' },+ ],+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const file = ctx.flags.file as string;+ const keyPath = ctx.flags.key as string | undefined;+ const genKeys = ctx.flags['generate-keys'] as boolean;+ const keyDir = ctx.flags['key-dir'] as string || '.rvfa-keys';+ const signer = ctx.flags.signer as string | undefined;+ if (!file) return fail('--file is required');++ try {+ const signing = await import('../appliance/rvfa-signing.js');++ if (genKeys) {+ hdr('Generating Ed25519 Key Pair');+ const kp = await signing.generateKeyPair();+ const paths = await signing.saveKeyPair(kp, keyDir);+ output.printSuccess(`Public key: ${paths.publicKeyPath}`);+ output.printSuccess(`Private key: ${paths.privateKeyPath}`);+ output.printInfo(`Fingerprint: ${kp.fingerprint}`);+ output.writeln(output.dim(' Keep the private key secure. Share only the public key.'));+ output.writeln();+ }++ if (!(await requireFile(file))) return { success: false, exitCode: 1 };+ hdr('Signing RVFA Appliance');++ let privateKey: Buffer;+ if (keyPath) {+ const fs = await import('fs');+ privateKey = fs.readFileSync(keyPath);+ } else {+ const kp = await signing.loadKeyPair(keyDir);+ privateKey = kp.privateKey;+ }++ const s = new signing.RvfaSigner(privateKey);+ const meta = await s.signAppliance(file);+ output.printSuccess('Appliance signed successfully');+ output.printInfo(`Algorithm: ${meta.algorithm}`);+ output.printInfo(`Fingerprint: ${meta.publicKeyFingerprint}`);+ output.printInfo(`Signed at: ${meta.signedAt}`);+ if (signer) output.printInfo(`Signed by: ${signer}`);+ output.printInfo(`Signature: ${meta.signature.slice(0, 32)}...`);+ return { success: true, data: meta };+ } catch (err) {+ return fail('Signing failed', errMsg(err));+ }+ },+};++// PUBLISH+export const publishCommand: Command = {+ name: 'publish',+ description: 'Publish an RVFA appliance to IPFS via Pinata',+ options: [+ { name: 'file', short: 'f', type: 'string', description: 'Path to .rvf file', required: true },+ { name: 'name', short: 'n', type: 'string', description: 'Publication name' },+ { name: 'description', type: 'string', description: 'Description' },+ ],+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const file = ctx.flags.file as string;+ if (!file) return fail('--file is required');+ if (!(await requireFile(file))) return { success: false, exitCode: 1 };++ try {+ const dist = await import('../appliance/rvfa-distribution.js');++ hdr('Publishing RVFA to IPFS');+ output.printInfo(`File: ${file}`);+ output.writeln();++ const publisher = dist.createPublisher();+ const result = await publisher.publish(file, {+ name: ctx.flags.name as string | undefined,+ description: ctx.flags.description as string | undefined,+ });++ output.printSuccess('Published successfully');+ output.printInfo(`CID: ${output.bold(result.cid)}`);+ output.printInfo(`Size: ${fmtSize(result.size)}`);+ output.printInfo(`Gateway: ${result.gatewayUrl}`);+ return { success: true, data: result };+ } catch (err) {+ return fail('Publishing failed', errMsg(err));+ }+ },+};++// UPDATE (hot-patch)+export const updateAppCommand: Command = {+ name: 'update',+ description: 'Hot-patch a section in an RVFA appliance',+ options: [+ { name: 'file', short: 'f', type: 'string', description: 'Path to .rvf file', required: true },+ { name: 'section', short: 's', type: 'string', description: 'Section to patch (e.g. ruflo, models)', required: true },+ { name: 'patch', short: 'p', type: 'string', description: 'Path to .rvfp patch file' },+ { name: 'data', short: 'd', type: 'string', description: 'Path to new section data (creates patch automatically)' },+ { name: 'version', type: 'string', description: 'Patch version', default: '0.0.1' },+ { name: 'no-backup', type: 'boolean', description: 'Skip backup creation' },+ { name: 'public-key', type: 'string', description: 'Path to public key for patch verification' },+ ],+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const file = ctx.flags.file as string;+ const section = ctx.flags.section as string;+ const patchPath = ctx.flags.patch as string | undefined;+ const dataPath = ctx.flags.data as string | undefined;+ if (!file || !section) return fail('--file and --section are required');+ if (!patchPath && !dataPath) return fail('Provide --patch (RVFP file) or --data (raw section data)');+ if (!(await requireFile(file))) return { success: false, exitCode: 1 };++ try {+ const dist = await import('../appliance/rvfa-distribution.js');+ const { RvfaReader } = await import('../appliance/rvfa-format.js');+ const fs = await import('fs');++ hdr('RVFA Hot-Patch Update');+ output.printInfo(`Appliance: ${file}`);+ output.printInfo(`Section: ${section}`);+ output.writeln();++ let patchBuf: Buffer;++ if (patchPath) {+ if (!(await requireFile(patchPath))) return { success: false, exitCode: 1 };+ patchBuf = fs.readFileSync(patchPath);+ output.printInfo(`Patch file: ${patchPath} (${fmtSize(patchBuf.length)})`);+ } else {+ if (!(await requireFile(dataPath!))) return { success: false, exitCode: 1 };+ const newData = fs.readFileSync(dataPath!);+ const reader = await RvfaReader.fromFile(file);+ const appHdr = reader.getHeader();+ output.printInfo(`Creating patch for section "${section}" (${fmtSize(newData.length)} new data)`);+ patchBuf = await dist.RvfaPatcher.createPatch({+ targetName: appHdr.name,+ targetVersion: appHdr.appVersion,+ sectionId: section,+ sectionData: newData,+ patchVersion: ctx.flags.version as string || '0.0.1',+ compression: 'gzip',+ });+ }++ let pubKey: Buffer | undefined;+ if (ctx.flags['public-key']) {+ const pkPath = ctx.flags['public-key'] as string;+ if (!(await requireFile(pkPath))) return { success: false, exitCode: 1 };+ pubKey = fs.readFileSync(pkPath);+ }++ const result = await dist.RvfaPatcher.applyPatch(file, patchBuf, {+ backup: !(ctx.flags['no-backup'] as boolean),+ verify: true,+ publicKey: pubKey,+ });++ if (result.success) {+ output.printSuccess(`Section "${result.patchedSection}" updated successfully`);+ output.printInfo(`New size: ${fmtSize(result.newSize)}`);+ if (result.backupPath) output.printInfo(`Backup: ${result.backupPath}`);+ } else {+ output.printError('Patch failed');+ result.errors.forEach(e => output.writeln(` ${output.error('X')} ${e}`));+ }+ return { success: result.success, exitCode: result.success ? 0 : 1, data: result };+ } catch (err) {+ return fail('Update failed', errMsg(err));+ }+ },+};diff --git a/v3/@claude-flow/cli/src/commands/appliance.ts b/v3/@claude-flow/cli/src/commands/appliance.tsindex f7f0263f0a..ce2cb93874 100644--- a/v3/@claude-flow/cli/src/commands/appliance.ts+++ b/v3/@claude-flow/cli/src/commands/appliance.ts@@ -1,10 +1,11 @@/*** V3 CLI Appliance Command- * Self-contained RVFA appliance management (build, inspect, verify, extract, run)+ * Self-contained RVFA appliance management (build, inspect, verify, extract, run, sign, publish, update)*/import type { Command, CommandContext, CommandResult } from '../types.js';import { output } from '../output.js';+import { signCommand, publishCommand, updateAppCommand } from './appliance-advanced.js';interface RvfaSection {id: string;@@ -402,13 +403,16 @@ export const applianceCommand: Command = {name: 'appliance',description: 'Self-contained RVFA appliance management (build, inspect, verify, extract, run)',aliases: ['rvfa'],- subcommands: [buildCommand, inspectCommand, verifyCommand, extractCommand, runCommand],+ subcommands: [buildCommand, inspectCommand, verifyCommand, extractCommand, runCommand, signCommand, publishCommand, updateAppCommand],examples: [{ command: 'ruflo appliance build -p cloud', description: 'Build a cloud appliance' },{ command: 'ruflo appliance inspect -f ruflo.rvf', description: 'Inspect appliance contents' },{ command: 'ruflo appliance verify -f ruflo.rvf', description: 'Verify integrity' },{ command: 'ruflo appliance extract -f ruflo.rvf', description: 'Extract sections' },{ command: 'ruflo appliance run -f ruflo.rvf', description: 'Boot and run appliance' },+ { command: 'ruflo appliance sign -f ruflo.rvf --generate-keys', description: 'Generate keys and sign' },+ { command: 'ruflo appliance publish -f ruflo.rvf', description: 'Publish to IPFS via Pinata' },+ { command: 'ruflo appliance update -f ruflo.rvf -s ruflo -d ./new-ruflo.bin', description: 'Hot-patch a section' },],action: async (): Promise<CommandResult> => {output.writeln();@@ -422,6 +426,9 @@ export const applianceCommand: Command = {'verify - Verify appliance integrity and run capability tests','extract - Extract all sections from an appliance','run - Boot and run an RVFA appliance',+ 'sign - Sign an appliance with Ed25519 for tamper detection',+ 'publish - Publish an appliance to IPFS via Pinata',+ 'update - Hot-patch a section in an appliance',]);output.writeln();output.writeln('Profiles:');diff --git a/v3/__tests__/appliance/gguf-engine.test.ts b/v3/__tests__/appliance/gguf-engine.test.tsnew file mode 100644index 0000000000..6ecc6da13e--- /dev/null+++ b/v3/__tests__/appliance/gguf-engine.test.ts@@ -0,0 +1,541 @@+/**+ * GGUF inference engine tests.+ *+ * Uses the Node.js built-in test runner (node:test).+ * Run: npx tsx --test v3/__tests__/appliance/gguf-engine.test.ts+ */++import { describe, it, beforeEach, afterEach } from 'node:test';+import assert from 'node:assert/strict';+import { writeFileSync, unlinkSync, mkdirSync, existsSync, readFileSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import { createHash } from 'node:crypto';+import {+ parseGgufHeader,+ GgufEngine,+ type GgufMetadata,+} from '../../@claude-flow/cli/src/appliance/gguf-engine.js';++// ---------------------------------------------------------------------------+// GGUF Binary Helpers+// ---------------------------------------------------------------------------++const GGUF_MAGIC_LE = 0x46554747; // "GGUF" in little-endian++/**+ * Write a GGUF string field: [length u64 LE][utf-8 bytes].+ */+function ggufString(str: string): Buffer {+ const strBuf = Buffer.from(str, 'utf-8');+ const lenBuf = Buffer.alloc(8);+ lenBuf.writeBigUInt64LE(BigInt(strBuf.length), 0);+ return Buffer.concat([lenBuf, strBuf]);+}++/**+ * Write a GGUF KV entry: [key_string][value_type u32 LE][value_data].+ * Supports STRING (type 8) and UINT32 (type 4) values.+ */+function ggufKvString(key: string, value: string): Buffer {+ const keyBuf = ggufString(key);+ const typeBuf = Buffer.alloc(4);+ typeBuf.writeUInt32LE(8, 0); // STRING type+ const valueBuf = ggufString(value);+ return Buffer.concat([keyBuf, typeBuf, valueBuf]);+}++function ggufKvUint32(key: string, value: number): Buffer {+ const keyBuf = ggufString(key);+ const typeBuf = Buffer.alloc(4);+ typeBuf.writeUInt32LE(4, 0); // UINT32 type+ const valueBuf = Buffer.alloc(4);+ valueBuf.writeUInt32LE(value, 0);+ return Buffer.concat([keyBuf, typeBuf, valueBuf]);+}++/**+ * Build a minimal valid GGUF v3 binary buffer with the given KV pairs.+ */+function buildGgufBuffer(options?: {+ version?: number;+ tensorCount?: number;+ kvEntries?: Buffer[];+}): Buffer {+ const version = options?.version ?? 3;+ const tensorCount = options?.tensorCount ?? 0;+ const kvEntries = options?.kvEntries ?? [+ ggufKvString('general.architecture', 'llama'),+ ggufKvString('general.name', 'test-model'),+ ];++ const magicBuf = Buffer.alloc(4);+ magicBuf.writeUInt32LE(GGUF_MAGIC_LE, 0);++ const versionBuf = Buffer.alloc(4);+ versionBuf.writeUInt32LE(version, 0);++ const tensorCountBuf = Buffer.alloc(8);+ tensorCountBuf.writeBigUInt64LE(BigInt(tensorCount), 0);++ const kvCountBuf = Buffer.alloc(8);+ kvCountBuf.writeBigUInt64LE(BigInt(kvEntries.length), 0);++ return Buffer.concat([+ magicBuf,+ versionBuf,+ tensorCountBuf,+ kvCountBuf,+ ...kvEntries,+ ]);+}++// ---------------------------------------------------------------------------+// Temp file management+// ---------------------------------------------------------------------------++const cleanupPaths: string[] = [];++function tmpPath(suffix: string): string {+ const p = join(+ tmpdir(),+ `gguf-test-${Date.now()}-${Math.random().toString(36).slice(2)}${suffix}`,+ );+ cleanupPaths.push(p);+ return p;+}++function writeGgufFile(buf: Buffer): string {+ const p = tmpPath('.gguf');+ writeFileSync(p, buf);+ return p;+}++afterEach(() => {+ for (const p of cleanupPaths) {+ try { unlinkSync(p); } catch { /* ignore */ }+ }+ cleanupPaths.length = 0;+});++// ---------------------------------------------------------------------------+// 1. GGUF header parsing+// ---------------------------------------------------------------------------++describe('parseGgufHeader', () => {+ it('parses a minimal GGUF v3 file with string KV entries', async () => {+ const buf = buildGgufBuffer();+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);++ assert.equal(meta.magic, 'GGUF');+ assert.equal(meta.version, 3);+ assert.equal(meta.tensorCount, 0);+ assert.equal(meta.kvCount, 2);+ assert.equal(meta.architecture, 'llama');+ assert.equal(meta.name, 'test-model');+ });++ it('supports GGUF version 2', async () => {+ const buf = buildGgufBuffer({ version: 2 });+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.version, 2);+ assert.equal(meta.architecture, 'llama');+ });++ it('supports GGUF version 3', async () => {+ const buf = buildGgufBuffer({ version: 3 });+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.version, 3);+ });++ it('parses tensor count correctly', async () => {+ const buf = buildGgufBuffer({ tensorCount: 42 });+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.tensorCount, 42);+ });++ it('parses integer KV entries (context_length, embedding_length)', async () => {+ const kvEntries = [+ ggufKvString('general.architecture', 'llama'),+ ggufKvString('general.name', 'test-model'),+ ggufKvUint32('llama.context_length', 4096),+ ggufKvUint32('llama.embedding_length', 2048),+ ];+ const buf = buildGgufBuffer({ kvEntries });+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.contextLength, 4096);+ assert.equal(meta.embeddingLength, 2048);+ });++ it('rejects a file with invalid magic bytes', async () => {+ const buf = Buffer.alloc(64);+ buf.writeUInt32LE(0xDEADBEEF, 0); // wrong magic+ buf.writeUInt32LE(3, 4); // version+ const filePath = writeGgufFile(buf);++ await assert.rejects(+ () => parseGgufHeader(filePath),+ /Invalid GGUF magic/,+ );+ });++ it('rejects unsupported GGUF version (version 1)', async () => {+ const buf = buildGgufBuffer({ version: 1 });+ const filePath = writeGgufFile(buf);++ await assert.rejects(+ () => parseGgufHeader(filePath),+ /Unsupported GGUF version/,+ );+ });++ it('rejects unsupported GGUF version (version 99)', async () => {+ const buf = buildGgufBuffer({ version: 99 });+ const filePath = writeGgufFile(buf);++ await assert.rejects(+ () => parseGgufHeader(filePath),+ /Unsupported GGUF version/,+ );+ });++ it('handles a truncated buffer gracefully (partial KV data)', async () => {+ // Build a valid header but truncate partway through KV entries+ const fullBuf = buildGgufBuffer({+ kvEntries: [+ ggufKvString('general.architecture', 'llama'),+ ggufKvString('general.name', 'test-model'),+ ],+ });+ // Truncate the buffer to cut off the second KV entry+ const truncatedLen = 24 + 30; // preamble + first KV, partial second+ const truncated = fullBuf.subarray(0, Math.min(truncatedLen, fullBuf.length));+ const filePath = writeGgufFile(truncated);++ // Should not throw -- metadata is partially parsed+ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.magic, 'GGUF');+ assert.equal(meta.version, 3);+ assert.equal(meta.kvCount, 2);+ });++ it('reports fileSize correctly', async () => {+ const buf = buildGgufBuffer();+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.fileSize, buf.length);+ });++ it('stores all parsed metadata in the metadata map', async () => {+ const buf = buildGgufBuffer();+ const filePath = writeGgufFile(buf);++ const meta = await parseGgufHeader(filePath);+ assert.equal(meta.metadata['general.architecture'], 'llama');+ assert.equal(meta.metadata['general.name'], 'test-model');+ });+});++// ---------------------------------------------------------------------------+// 2. GgufEngine lifecycle+// ---------------------------------------------------------------------------++describe('GgufEngine', () => {+ let engine: GgufEngine;++ beforeEach(() => {+ engine = new GgufEngine({+ contextSize: 2048,+ maxTokens: 256,+ temperature: 0.5,+ verbose: false,+ });+ });++ afterEach(async () => {+ await engine.shutdown();+ });++ it('constructs with provided config', () => {+ assert.ok(engine);+ });++ it('initialize succeeds even without node-llama-cpp', async () => {+ await engine.initialize();+ // Should not throw -- degrades gracefully+ });++ it('loadModel parses GGUF header from a test file', async () => {+ await engine.initialize();++ const buf = buildGgufBuffer({+ kvEntries: [+ ggufKvString('general.architecture', 'llama'),+ ggufKvString('general.name', 'engine-test-model'),+ ],+ });+ const filePath = writeGgufFile(buf);++ const meta = await engine.loadModel(filePath);+ assert.equal(meta.architecture, 'llama');+ assert.equal(meta.name, 'engine-test-model');+ });++ it('getLoadedModels returns models after loadModel', async () => {+ await engine.initialize();++ const buf = buildGgufBuffer();+ const filePath = writeGgufFile(buf);++ await engine.loadModel(filePath);+ const models = engine.getLoadedModels();+ assert.equal(models.length, 1);+ assert.equal(models[0].architecture, 'llama');+ });++ it('shutdown clears loaded models', async () => {+ await engine.initialize();++ const buf = buildGgufBuffer();+ const filePath = writeGgufFile(buf);++ await engine.loadModel(filePath);+ assert.equal(engine.getLoadedModels().length, 1);++ await engine.shutdown();+ assert.equal(engine.getLoadedModels().length, 0);+ });+});++// ---------------------------------------------------------------------------+// 3. Generate in metadata-only mode+// ---------------------------------------------------------------------------++describe('GgufEngine.generate (metadata-only)', () => {+ it('returns a metadata-only response when node-llama-cpp is unavailable', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ const buf = buildGgufBuffer({+ kvEntries: [+ ggufKvString('general.architecture', 'llama'),+ ggufKvString('general.name', 'fallback-model'),+ ],+ });+ const filePath = writeGgufFile(buf);+ await engine.loadModel(filePath);++ const response = await engine.generate({ prompt: 'Hello world' });+ assert.equal(response.metadataOnly, true);+ assert.ok(response.text.includes('metadata-only'));+ assert.ok(response.text.includes('fallback-model'));+ assert.equal(response.tokensUsed, 0);+ assert.ok(response.latencyMs >= 0);++ await engine.shutdown();+ });++ it('returns a no-model placeholder when no model is loaded', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ const response = await engine.generate({ prompt: 'Hello world' });+ assert.equal(response.metadataOnly, true);+ assert.ok(response.text.includes('No model loaded'));++ await engine.shutdown();+ });+});++// ---------------------------------------------------------------------------+// 4. KV cache persistence (RVKV format)+// ---------------------------------------------------------------------------++describe('KV cache persistence', () => {+ it('writes and reads back KV cache entries (round-trip)', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ // Load a model so there's an active model path+ const buf = buildGgufBuffer();+ const filePath = writeGgufFile(buf);+ await engine.loadModel(filePath);++ // Store some entries+ engine.setKvEntry('key-alpha', Buffer.from('value-alpha'));+ engine.setKvEntry('key-beta', Buffer.from('value-beta'));+ engine.setKvEntry('key-gamma', Buffer.from('value-gamma'));++ // Persist+ const cachePath = tmpPath('.rvkv');+ await engine.persistKvCache(cachePath);++ // Create a fresh engine and load the cache+ const engine2 = new GgufEngine({ verbose: false });+ await engine2.initialize();+ await engine2.loadKvCache(cachePath);++ assert.deepEqual(engine2.getKvEntry('key-alpha'), Buffer.from('value-alpha'));+ assert.deepEqual(engine2.getKvEntry('key-beta'), Buffer.from('value-beta'));+ assert.deepEqual(engine2.getKvEntry('key-gamma'), Buffer.from('value-gamma'));++ await engine.shutdown();+ await engine2.shutdown();+ });++ it('RVKV file starts with magic "RVKV" (0x564B5652 LE)', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();+ const buf = buildGgufBuffer();+ await engine.loadModel(writeGgufFile(buf));++ engine.setKvEntry('test', Buffer.from('data'));++ const cachePath = tmpPath('.rvkv');+ await engine.persistKvCache(cachePath);++ const data = readFileSync(cachePath);+ assert.equal(data.readUInt32LE(0), 0x564B5652, 'Magic should be RVKV');+ assert.equal(data.readUInt32LE(4), 1, 'Version should be 1');++ await engine.shutdown();+ });++ it('loadKvCache rejects a file with invalid magic', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ const badFile = tmpPath('.rvkv');+ const badBuf = Buffer.alloc(64);+ badBuf.writeUInt32LE(0xDEADBEEF, 0);+ writeFileSync(badFile, badBuf);++ await assert.rejects(+ () => engine.loadKvCache(badFile),+ /Invalid KV cache magic/,+ );++ await engine.shutdown();+ });++ it('loadKvCache rejects a file that is too small', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ const smallFile = tmpPath('.rvkv');+ writeFileSync(smallFile, Buffer.alloc(10));++ await assert.rejects(+ () => engine.loadKvCache(smallFile),+ /too small/,+ );++ await engine.shutdown();+ });++ it('SHA256 footer is verified on loadKvCache', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();+ const ggufBuf = buildGgufBuffer();+ await engine.loadModel(writeGgufFile(ggufBuf));++ engine.setKvEntry('important', Buffer.from('secret-data'));++ const cachePath = tmpPath('.rvkv');+ await engine.persistKvCache(cachePath);++ // Tamper with the SHA256 footer (last 32 bytes) to trigger hash mismatch+ const data = readFileSync(cachePath);+ const tampered = Buffer.from(data);+ // Flip a byte in the footer hash area (last 32 bytes)+ tampered[tampered.length - 1] ^= 0xFF;+ writeFileSync(cachePath, tampered);++ const engine2 = new GgufEngine({ verbose: false });+ await engine2.initialize();++ await assert.rejects(+ () => engine2.loadKvCache(cachePath),+ /hash mismatch/,+ );++ await engine.shutdown();+ await engine2.shutdown();+ });++ it('handles empty KV cache (zero entries)', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();+ const ggufBuf = buildGgufBuffer();+ await engine.loadModel(writeGgufFile(ggufBuf));++ // No entries set -- persist should still work+ const cachePath = tmpPath('.rvkv');+ await engine.persistKvCache(cachePath);++ const engine2 = new GgufEngine({ verbose: false });+ await engine2.initialize();+ await engine2.loadKvCache(cachePath);++ assert.equal(engine2.getKvEntry('nonexistent'), undefined);++ await engine.shutdown();+ await engine2.shutdown();+ });+});++// ---------------------------------------------------------------------------+// 5. Stream+// ---------------------------------------------------------------------------++describe('GgufEngine.stream', () => {+ it('yields at least one token from the async iterator', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ const ggufBuf = buildGgufBuffer({+ kvEntries: [+ ggufKvString('general.architecture', 'llama'),+ ggufKvString('general.name', 'stream-test'),+ ],+ });+ await engine.loadModel(writeGgufFile(ggufBuf));++ const tokens: string[] = [];+ for await (const token of engine.stream({ prompt: 'Hello' })) {+ tokens.push(token);+ }++ assert.ok(tokens.length >= 1, 'Stream should yield at least one token');+ // In metadata-only mode, it yields the full metadata response as one chunk+ assert.ok(tokens[0].includes('metadata-only'));++ await engine.shutdown();+ });++ it('yields the no-model fallback when no model is loaded', async () => {+ const engine = new GgufEngine({ verbose: false });+ await engine.initialize();++ const tokens: string[] = [];+ for await (const token of engine.stream({ prompt: 'Hello' })) {+ tokens.push(token);+ }++ assert.ok(tokens.length >= 1);+ assert.ok(tokens[0].includes('No model loaded'));++ await engine.shutdown();+ });+});diff --git a/v3/__tests__/appliance/rvfa-distribution.test.ts b/v3/__tests__/appliance/rvfa-distribution.test.tsnew file mode 100644index 0000000000..f748dab301--- /dev/null+++ b/v3/__tests__/appliance/rvfa-distribution.test.ts@@ -0,0 +1,641 @@+/**+ * RVFA Distribution & Hot-Patch module tests.+ *+ * Uses the Node.js built-in test runner (node:test).+ * Run: npx tsx --test v3/__tests__/appliance/rvfa-distribution.test.ts+ */++import { describe, it, afterEach } from 'node:test';+import assert from 'node:assert/strict';+import { writeFileSync, unlinkSync, existsSync, readFileSync, mkdirSync, rmSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import {+ RvfaPatcher,+ RvfaPublisher,+ type RvfpHeader,+ type CreatePatchOptions,+} from '../../@claude-flow/cli/src/appliance/rvfa-distribution.js';+import {+ RvfaWriter,+ RvfaReader,+ createDefaultHeader,+} from '../../@claude-flow/cli/src/appliance/rvfa-format.js';++// ---------------------------------------------------------------------------+// Helpers+// ---------------------------------------------------------------------------++const cleanupPaths: string[] = [];++function tmpPath(suffix: string): string {+ const p = join(+ tmpdir(),+ `rvfa-dist-test-${Date.now()}-${Math.random().toString(36).slice(2)}${suffix}`,+ );+ cleanupPaths.push(p);+ return p;+}++function tmpDir(): string {+ const d = join(+ tmpdir(),+ `rvfa-dist-dir-${Date.now()}-${Math.random().toString(36).slice(2)}`,+ );+ mkdirSync(d, { recursive: true });+ cleanupPaths.push(d);+ return d;+}++/** Build a test RVFA binary with the given sections. */+function buildTestRvfa(+ name = 'test-appliance',+ version = '3.5.0',+ sections?: Array<{ id: string; data: string }>,+): Buffer {+ const header = createDefaultHeader('cloud');+ const writer = new RvfaWriter({ ...header, name, appVersion: version });+ const secs = sections ?? [+ { id: 'kernel', data: 'kernel-payload-original' },+ { id: 'runtime', data: 'runtime-payload-original' },+ { id: 'ruflo', data: 'ruflo-payload-original' },+ ];+ for (const s of secs) {+ writer.addSection(s.id, Buffer.from(s.data), { compression: 'none' });+ }+ return writer.build();+}++function writeTestRvfa(+ name = 'test-appliance',+ version = '3.5.0',+ sections?: Array<{ id: string; data: string }>,+): string {+ const buf = buildTestRvfa(name, version, sections);+ const p = tmpPath('.rvf');+ writeFileSync(p, buf);+ return p;+}++afterEach(() => {+ for (const p of cleanupPaths) {+ try {+ if (existsSync(p)) {+ const s = require('node:fs').statSync(p);+ if (s.isDirectory()) rmSync(p, { recursive: true, force: true });+ else unlinkSync(p);+ }+ } catch { /* ignore */ }+ }+ cleanupPaths.length = 0;+});++// ---------------------------------------------------------------------------+// 1. RVFP patch creation+// ---------------------------------------------------------------------------++describe('RvfaPatcher.createPatch', () => {+ it('creates a patch with RVFP magic bytes', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'test-appliance',+ targetVersion: '3.5.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('new-kernel-data'),+ patchVersion: '1.0.0',+ });++ assert.equal(patch.subarray(0, 4).toString('ascii'), 'RVFP');+ });++ it('creates a patch with correct version number', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'test-appliance',+ targetVersion: '3.5.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('new-kernel-data'),+ patchVersion: '1.0.0',+ });++ assert.equal(patch.readUInt32LE(4), 1, 'Version should be 1');+ });++ it('includes all header fields in the patch', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'my-app',+ targetVersion: '2.0.0',+ sectionId: 'runtime',+ sectionData: Buffer.from('updated-runtime'),+ patchVersion: '1.1.0',+ });++ const header = RvfaPatcher.parsePatchHeader(patch);+ assert.equal(header.magic, 'RVFP');+ assert.equal(header.version, 1);+ assert.equal(header.targetApplianceName, 'my-app');+ assert.equal(header.targetApplianceVersion, '2.0.0');+ assert.equal(header.targetSection, 'runtime');+ assert.equal(header.patchVersion, '1.1.0');+ assert.equal(typeof header.created, 'string');+ assert.ok(header.created.length > 0);+ assert.equal(typeof header.newSectionSha256, 'string');+ assert.ok(header.newSectionSha256.length > 0);+ });+});++// ---------------------------------------------------------------------------+// 2. RVFP patch header+// ---------------------------------------------------------------------------++describe('RvfaPatcher.parsePatchHeader', () => {+ it('extracts all fields from a valid patch', async () => {+ const sectionData = Buffer.from('test-section-content');+ const patch = await RvfaPatcher.createPatch({+ targetName: 'header-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData,+ patchVersion: '0.1.0',+ compression: 'none',+ });++ const header = RvfaPatcher.parsePatchHeader(patch);+ assert.equal(header.targetApplianceName, 'header-test');+ assert.equal(header.targetApplianceVersion, '1.0.0');+ assert.equal(header.targetSection, 'kernel');+ assert.equal(header.patchVersion, '0.1.0');+ assert.equal(header.compression, 'none');+ assert.equal(header.newSectionSize, sectionData.length);+ });++ it('rejects a buffer with wrong magic', () => {+ const bad = Buffer.alloc(64);+ bad.write('NOPE', 0, 'ascii');+ assert.throws(+ () => RvfaPatcher.parsePatchHeader(bad),+ /Invalid RVFP magic/,+ );+ });++ it('rejects a buffer that is too small', () => {+ const small = Buffer.alloc(8);+ small.write('RVFP', 0, 'ascii');+ assert.throws(+ () => RvfaPatcher.parsePatchHeader(small),+ /too small/,+ );+ });+});++// ---------------------------------------------------------------------------+// 3. Patch verification+// ---------------------------------------------------------------------------++describe('RvfaPatcher.verifyPatch', () => {+ it('returns valid=true for a well-formed patch', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'verify-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('valid-content'),+ patchVersion: '0.1.0',+ });++ const result = await RvfaPatcher.verifyPatch(patch);+ assert.ok(result.valid, `Expected valid but got errors: ${result.errors.join(', ')}`);+ assert.equal(result.errors.length, 0);+ });++ it('returns valid=false for a tampered patch payload', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'tamper-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('original-payload-data'),+ patchVersion: '0.1.0',+ });++ const tampered = Buffer.from(patch);+ // Tamper with the payload area (after header, before footer)+ const headerLen = tampered.readUInt32LE(8);+ const payloadOffset = 12 + headerLen;+ if (payloadOffset < tampered.length - 32) {+ tampered[payloadOffset] ^= 0xFF;+ }++ const result = await RvfaPatcher.verifyPatch(tampered);+ assert.ok(!result.valid, 'Tampered patch should fail verification');+ assert.ok(result.errors.some((e) => e.includes('SHA256')));+ });++ it('returns valid=false for a tampered footer', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'footer-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('some-payload'),+ patchVersion: '0.1.0',+ });++ const tampered = Buffer.from(patch);+ // Tamper with the last byte of the footer+ tampered[tampered.length - 1] ^= 0xFF;++ const result = await RvfaPatcher.verifyPatch(tampered);+ assert.ok(!result.valid, 'Tampered footer should fail verification');+ });+});++// ---------------------------------------------------------------------------+// 4. Patch application+// ---------------------------------------------------------------------------++describe('RvfaPatcher.applyPatch', () => {+ it('replaces the target section and preserves others', async () => {+ const rvfaPath = writeTestRvfa('patch-app', '3.5.0');++ const newKernelData = Buffer.from('brand-new-kernel-payload');+ const patch = await RvfaPatcher.createPatch({+ targetName: 'patch-app',+ targetVersion: '3.5.0',+ sectionId: 'kernel',+ sectionData: newKernelData,+ patchVersion: '1.0.0',+ });++ const result = await RvfaPatcher.applyPatch(rvfaPath, patch, { verify: true });++ assert.ok(result.success, `Apply failed: ${result.errors.join(', ')}`);+ assert.equal(result.patchedSection, 'kernel');+ assert.ok(result.newSize > 0);++ // Verify the patched file+ const patchedBuf = readFileSync(rvfaPath);+ const reader = RvfaReader.fromBuffer(patchedBuf);++ // Target section replaced+ const kernel = reader.extractSection('kernel');+ assert.equal(kernel.toString('utf-8'), 'brand-new-kernel-payload');++ // Other sections untouched+ const runtime = reader.extractSection('runtime');+ assert.equal(runtime.toString('utf-8'), 'runtime-payload-original');++ const ruflo = reader.extractSection('ruflo');+ assert.equal(ruflo.toString('utf-8'), 'ruflo-payload-original');+ });++ it('creates a backup file', async () => {+ const rvfaPath = writeTestRvfa('backup-test', '3.5.0');++ const patch = await RvfaPatcher.createPatch({+ targetName: 'backup-test',+ targetVersion: '3.5.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('new-kernel'),+ patchVersion: '1.0.0',+ });++ const result = await RvfaPatcher.applyPatch(rvfaPath, patch, { backup: true });++ assert.ok(result.success);+ assert.ok(result.backupPath, 'Backup path should be set');+ assert.ok(existsSync(result.backupPath!), 'Backup file should exist');+ cleanupPaths.push(result.backupPath!);+ });++ it('new RVFA passes verify() after patching', async () => {+ const rvfaPath = writeTestRvfa('verify-after-patch', '3.5.0');++ const patch = await RvfaPatcher.createPatch({+ targetName: 'verify-after-patch',+ targetVersion: '3.5.0',+ sectionId: 'runtime',+ sectionData: Buffer.from('updated-runtime-payload'),+ patchVersion: '1.0.0',+ });++ const result = await RvfaPatcher.applyPatch(rvfaPath, patch, { verify: true });+ assert.ok(result.success, `Apply failed: ${result.errors.join(', ')}`);++ // Double-check: read back and verify independently+ const patchedBuf = readFileSync(rvfaPath);+ const reader = RvfaReader.fromBuffer(patchedBuf);+ const verifyResult = reader.verify();+ assert.ok(verifyResult.valid, `Verify failed: ${verifyResult.errors.join(', ')}`);+ });++ it('footer SHA256 is updated after patching', async () => {+ const rvfaPath = writeTestRvfa('footer-update', '3.5.0');++ // Read original footer+ const originalBuf = readFileSync(rvfaPath);+ const originalFooter = originalBuf.subarray(originalBuf.length - 32);++ const patch = await RvfaPatcher.createPatch({+ targetName: 'footer-update',+ targetVersion: '3.5.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('different-kernel-data'),+ patchVersion: '1.0.0',+ });++ await RvfaPatcher.applyPatch(rvfaPath, patch);++ // Read new footer+ const patchedBuf = readFileSync(rvfaPath);+ const newFooter = patchedBuf.subarray(patchedBuf.length - 32);++ assert.ok(!originalFooter.equals(newFooter), 'Footer SHA256 should change after patching');+ });+});++// ---------------------------------------------------------------------------+// 5. Patch for wrong target+// ---------------------------------------------------------------------------++describe('Patch target mismatch', () => {+ it('fails when patch targets a different appliance name', async () => {+ const rvfaPath = writeTestRvfa('correct-app', '3.5.0');++ const patch = await RvfaPatcher.createPatch({+ targetName: 'wrong-app',+ targetVersion: '3.5.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('new-data'),+ patchVersion: '1.0.0',+ });++ const result = await RvfaPatcher.applyPatch(rvfaPath, patch);+ assert.ok(!result.success, 'Should fail for wrong target app');+ assert.ok(+ result.errors.some((e) => e.includes('mismatch') || e.includes('wrong-app')),+ `Expected mismatch error, got: ${result.errors.join(', ')}`,+ );+ });++ it('fails when patch targets a different appliance version', async () => {+ const rvfaPath = writeTestRvfa('version-test', '3.5.0');++ const patch = await RvfaPatcher.createPatch({+ targetName: 'version-test',+ targetVersion: '9.9.9',+ sectionId: 'kernel',+ sectionData: Buffer.from('new-data'),+ patchVersion: '1.0.0',+ });++ const result = await RvfaPatcher.applyPatch(rvfaPath, patch);+ assert.ok(!result.success, 'Should fail for wrong target version');+ assert.ok(+ result.errors.some((e) => e.includes('mismatch') || e.includes('9.9.9')),+ );+ });++ it('fails when patch targets a nonexistent section', async () => {+ const rvfaPath = writeTestRvfa('section-test', '3.5.0');++ const patch = await RvfaPatcher.createPatch({+ targetName: 'section-test',+ targetVersion: '3.5.0',+ sectionId: 'nonexistent-section',+ sectionData: Buffer.from('new-data'),+ patchVersion: '1.0.0',+ });++ const result = await RvfaPatcher.applyPatch(rvfaPath, patch);+ assert.ok(!result.success, 'Should fail for nonexistent section');+ assert.ok(+ result.errors.some((e) => e.includes('not found') || e.includes('nonexistent')),+ );+ });+});++// ---------------------------------------------------------------------------+// 6. Signed patch verification (via rvfa-signing integration)+// ---------------------------------------------------------------------------++describe('Signed patch', () => {+ // Note: The distribution module uses raw DER Ed25519 keys, not PEM.+ // We skip direct Ed25519 signing tests here since the signing module+ // is tested separately. We test that the signature field in the header+ // is properly set when a private key is provided.++ it('patch header contains signature when privateKey is provided', async () => {+ // Generate raw Ed25519 DER keys using crypto+ const { generateKeyPairSync } = await import('node:crypto');+ const keyPair = generateKeyPairSync('ed25519', {+ publicKeyEncoding: { type: 'spki', format: 'der' },+ privateKeyEncoding: { type: 'pkcs8', format: 'der' },+ });++ const patch = await RvfaPatcher.createPatch({+ targetName: 'signed-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('signed-payload'),+ patchVersion: '1.0.0',+ privateKey: keyPair.privateKey as Buffer,+ signedBy: 'test-publisher',+ });++ const header = RvfaPatcher.parsePatchHeader(patch);+ assert.ok(header.signature, 'Signed patch should have a signature field');+ assert.equal(header.signedBy, 'test-publisher');+ assert.ok(header.signature!.length > 0);+ });++ it('unsigned patch has no signature field', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'unsigned-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('unsigned-payload'),+ patchVersion: '1.0.0',+ });++ const header = RvfaPatcher.parsePatchHeader(patch);+ assert.equal(header.signature, undefined);+ assert.equal(header.signedBy, undefined);+ });+});++// ---------------------------------------------------------------------------+// 7. Signed patch tamper detection+// ---------------------------------------------------------------------------++describe('Signed patch tamper detection', () => {+ it('verification fails when patch data is modified after signing', async () => {+ const { generateKeyPairSync } = await import('node:crypto');+ const keyPair = generateKeyPairSync('ed25519', {+ publicKeyEncoding: { type: 'spki', format: 'der' },+ privateKeyEncoding: { type: 'pkcs8', format: 'der' },+ });++ const patch = await RvfaPatcher.createPatch({+ targetName: 'tamper-sign-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('original-signed-data'),+ patchVersion: '1.0.0',+ privateKey: keyPair.privateKey as Buffer,+ signedBy: 'publisher',+ });++ // Tamper with the section payload+ const tampered = Buffer.from(patch);+ const headerLen = tampered.readUInt32LE(8);+ const payloadOffset = 12 + headerLen;+ if (payloadOffset < tampered.length - 32) {+ tampered[payloadOffset] ^= 0xFF;+ }++ // Integrity verification should fail (SHA256 mismatch)+ const result = await RvfaPatcher.verifyPatch(tampered);+ assert.ok(!result.valid, 'Tampered signed patch should fail verification');+ });+});++// ---------------------------------------------------------------------------+// 8. parsePatchHeader edge cases+// ---------------------------------------------------------------------------++describe('parsePatchHeader edge cases', () => {+ it('rejects a buffer with unsupported version', async () => {+ const patch = await RvfaPatcher.createPatch({+ targetName: 'version-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData: Buffer.from('data'),+ patchVersion: '1.0.0',+ });++ const tampered = Buffer.from(patch);+ tampered.writeUInt32LE(99, 4); // bad version++ assert.throws(+ () => RvfaPatcher.parsePatchHeader(tampered),+ /Unsupported RVFP version/,+ );+ });++ it('rejects a buffer with header length exceeding buffer size', async () => {+ const buf = Buffer.alloc(16);+ buf.write('RVFP', 0, 'ascii');+ buf.writeUInt32LE(1, 4); // version+ buf.writeUInt32LE(9999, 8); // header_len way too big++ assert.throws(+ () => RvfaPatcher.parsePatchHeader(buf),+ /too small/,+ );+ });+});++// ---------------------------------------------------------------------------+// 9. RvfaPublisher config+// ---------------------------------------------------------------------------++describe('RvfaPublisher', () => {+ it('constructor accepts JWT from config', () => {+ const publisher = new RvfaPublisher({+ pinataJwt: 'test-jwt-token-from-config',+ });+ assert.ok(publisher);+ });++ it('constructor accepts JWT from process.env', () => {+ const original = process.env.PINATA_API_JWT;+ process.env.PINATA_API_JWT = 'test-jwt-from-env';+ try {+ const publisher = new RvfaPublisher({});+ assert.ok(publisher);+ } finally {+ if (original !== undefined) {+ process.env.PINATA_API_JWT = original;+ } else {+ delete process.env.PINATA_API_JWT;+ }+ }+ });++ it('constructor throws when no JWT is available', () => {+ const original = process.env.PINATA_API_JWT;+ delete process.env.PINATA_API_JWT;+ try {+ assert.throws(+ () => new RvfaPublisher({ pinataJwt: '' }),+ /JWT/i,+ );+ } finally {+ if (original !== undefined) {+ process.env.PINATA_API_JWT = original;+ }+ }+ });+});++// ---------------------------------------------------------------------------+// 10. Publisher list (mock-safe)+// ---------------------------------------------------------------------------++describe('Publisher URL construction', () => {+ it('uses default gateway and API URLs', () => {+ const original = process.env.PINATA_API_JWT;+ process.env.PINATA_API_JWT = 'test-jwt';+ try {+ const publisher = new RvfaPublisher({});+ // We cannot call .list() without network, but we can verify+ // the publisher was created successfully with defaults+ assert.ok(publisher);+ } finally {+ if (original !== undefined) {+ process.env.PINATA_API_JWT = original;+ } else {+ delete process.env.PINATA_API_JWT;+ }+ }+ });++ it('accepts custom gateway and API URLs', () => {+ const publisher = new RvfaPublisher({+ pinataJwt: 'test-jwt',+ gatewayUrl: 'https://custom-gateway.example.com',+ apiUrl: 'https://custom-api.example.com',+ });+ assert.ok(publisher);+ });++ it('strips trailing slashes from URLs', () => {+ const publisher = new RvfaPublisher({+ pinataJwt: 'test-jwt',+ gatewayUrl: 'https://gateway.example.com///',+ apiUrl: 'https://api.example.com//',+ });+ // The publisher should be created without error (trailing slashes stripped internally)+ assert.ok(publisher);+ });+});++// ---------------------------------------------------------------------------+// 11. Gzip compression in patches+// ---------------------------------------------------------------------------++describe('Gzip-compressed patches', () => {+ it('creates and verifies a gzip-compressed patch', async () => {+ const sectionData = Buffer.alloc(1024, 0x42); // highly compressible+ const patch = await RvfaPatcher.createPatch({+ targetName: 'gzip-test',+ targetVersion: '1.0.0',+ sectionId: 'kernel',+ sectionData,+ patchVersion: '1.0.0',+ compression: 'gzip',+ });++ const header = RvfaPatcher.parsePatchHeader(patch);+ assert.equal(header.compression, 'gzip');++ const result = await RvfaPatcher.verifyPatch(patch);+ assert.ok(result.valid, `Gzip patch should verify: ${result.errors.join(', ')}`);+ });+});diff --git a/v3/__tests__/appliance/rvfa-signing.test.ts b/v3/__tests__/appliance/rvfa-signing.test.tsnew file mode 100644index 0000000000..83a05512d2--- /dev/null+++ b/v3/__tests__/appliance/rvfa-signing.test.ts@@ -0,0 +1,451 @@+/**+ * RVFA Ed25519 signing module tests.+ *+ * Uses the Node.js built-in test runner (node:test).+ * Run: npx tsx --test v3/__tests__/appliance/rvfa-signing.test.ts+ */++import { describe, it, afterEach } from 'node:test';+import assert from 'node:assert/strict';+import { writeFileSync, unlinkSync, existsSync, readFileSync, mkdirSync, rmSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import {+ generateKeyPair,+ saveKeyPair,+ loadKeyPair,+ RvfaSigner,+ RvfaVerifier,+ type RvfaKeyPair,+} from '../../@claude-flow/cli/src/appliance/rvfa-signing.js';+import {+ RvfaWriter,+ RvfaReader,+ createDefaultHeader,+} from '../../@claude-flow/cli/src/appliance/rvfa-format.js';++// ---------------------------------------------------------------------------+// Helpers+// ---------------------------------------------------------------------------++const cleanupPaths: string[] = [];++function tmpPath(suffix: string): string {+ const p = join(+ tmpdir(),+ `rvfa-sign-test-${Date.now()}-${Math.random().toString(36).slice(2)}${suffix}`,+ );+ cleanupPaths.push(p);+ return p;+}++function tmpDir(): string {+ const d = join(+ tmpdir(),+ `rvfa-sign-dir-${Date.now()}-${Math.random().toString(36).slice(2)}`,+ );+ mkdirSync(d, { recursive: true });+ cleanupPaths.push(d);+ return d;+}++function buildTestRvfa(name = 'test-appliance'): Buffer {+ const header = createDefaultHeader('cloud');+ const writer = new RvfaWriter({ ...header, name });+ writer.addSection('kernel', Buffer.from('kernel-data'), { compression: 'none' });+ writer.addSection('runtime', Buffer.from('runtime-data'), { compression: 'none' });+ writer.addSection('ruflo', Buffer.from('ruflo-data'), { compression: 'none' });+ return writer.build();+}++function writeTestRvfa(name = 'test-appliance'): string {+ const buf = buildTestRvfa(name);+ const p = tmpPath('.rvf');+ writeFileSync(p, buf);+ return p;+}++afterEach(() => {+ for (const p of cleanupPaths) {+ try {+ if (existsSync(p)) {+ const s = require('node:fs').statSync(p);+ if (s.isDirectory()) rmSync(p, { recursive: true, force: true });+ else unlinkSync(p);+ }+ } catch { /* ignore */ }+ }+ cleanupPaths.length = 0;+});++// ---------------------------------------------------------------------------+// 1. Key generation+// ---------------------------------------------------------------------------++describe('generateKeyPair', () => {+ it('produces a key pair with publicKey, privateKey, and fingerprint', async () => {+ const kp = await generateKeyPair();++ assert.ok(Buffer.isBuffer(kp.publicKey));+ assert.ok(Buffer.isBuffer(kp.privateKey));+ assert.equal(typeof kp.fingerprint, 'string');+ assert.ok(kp.fingerprint.length > 0);+ });++ it('public key is in PEM format (starts with BEGIN)', async () => {+ const kp = await generateKeyPair();+ const pubPem = kp.publicKey.toString('utf-8');+ assert.ok(pubPem.includes('BEGIN PUBLIC KEY'), 'Public key should be PEM-encoded');+ });++ it('private key is in PEM format (starts with BEGIN)', async () => {+ const kp = await generateKeyPair();+ const privPem = kp.privateKey.toString('utf-8');+ assert.ok(privPem.includes('BEGIN PRIVATE KEY'), 'Private key should be PEM-encoded');+ });++ it('generates distinct key pairs on each call', async () => {+ const kp1 = await generateKeyPair();+ const kp2 = await generateKeyPair();+ assert.ok(!kp1.publicKey.equals(kp2.publicKey), 'Public keys should differ');+ assert.ok(!kp1.privateKey.equals(kp2.privateKey), 'Private keys should differ');+ assert.notEqual(kp1.fingerprint, kp2.fingerprint, 'Fingerprints should differ');+ });+});++// ---------------------------------------------------------------------------+// 2. Key fingerprint+// ---------------------------------------------------------------------------++describe('Key fingerprint', () => {+ it('fingerprint is hex and 16 characters long', async () => {+ const kp = await generateKeyPair();+ assert.match(kp.fingerprint, /^[0-9a-f]{16}$/);+ });++ it('fingerprint is deterministic for the same key', async () => {+ const kp = await generateKeyPair();+ // Recreate a signer from the same private key -- fingerprint should match+ const signer = new RvfaSigner(kp.privateKey);+ // Sign something to verify signer is operational+ const rvfaPath = writeTestRvfa();+ const sigMeta = await signer.signAppliance(rvfaPath);+ assert.equal(sigMeta.publicKeyFingerprint, kp.fingerprint);+ });+});++// ---------------------------------------------------------------------------+// 3. Key save/load+// ---------------------------------------------------------------------------++describe('saveKeyPair / loadKeyPair', () => {+ it('round-trips a key pair through save and load', async () => {+ const original = await generateKeyPair();+ const dir = tmpDir();++ await saveKeyPair(original, dir, 'test-key');++ assert.ok(existsSync(join(dir, 'test-key.pub')), 'Public key file should exist');+ assert.ok(existsSync(join(dir, 'test-key.key')), 'Private key file should exist');++ const loaded = await loadKeyPair(dir, 'test-key');++ assert.ok(loaded.publicKey.equals(original.publicKey), 'Public key should round-trip');+ assert.ok(loaded.privateKey.equals(original.privateKey), 'Private key should round-trip');+ assert.equal(loaded.fingerprint, original.fingerprint, 'Fingerprint should round-trip');+ });++ it('uses default name "rvfa-signing" when none provided', async () => {+ const kp = await generateKeyPair();+ const dir = tmpDir();++ await saveKeyPair(kp, dir);++ assert.ok(existsSync(join(dir, 'rvfa-signing.pub')));+ assert.ok(existsSync(join(dir, 'rvfa-signing.key')));++ const loaded = await loadKeyPair(dir);+ assert.equal(loaded.fingerprint, kp.fingerprint);+ });+});++// ---------------------------------------------------------------------------+// 4. Sign appliance+// ---------------------------------------------------------------------------++describe('RvfaSigner.signAppliance', () => {+ it('signs an RVFA file and embeds signature metadata in the header', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const rvfaPath = writeTestRvfa();++ const sigMeta = await signer.signAppliance(rvfaPath, 'test-publisher');++ assert.equal(sigMeta.algorithm, 'ed25519');+ assert.equal(typeof sigMeta.signature, 'string');+ assert.ok(sigMeta.signature.length > 0);+ assert.equal(sigMeta.publicKeyFingerprint, kp.fingerprint);+ assert.equal(sigMeta.signedBy, 'test-publisher');+ assert.equal(sigMeta.scope, 'full');+ assert.equal(typeof sigMeta.signedAt, 'string');+ });++ it('signed file is still a valid RVFA (readable by RvfaReader)', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const rvfaPath = writeTestRvfa();++ await signer.signAppliance(rvfaPath);++ const buf = readFileSync(rvfaPath);+ const reader = RvfaReader.fromBuffer(buf);+ const header = reader.getHeader();+ assert.equal(header.name, 'test-appliance');+ assert.ok((header as any).signature, 'Header should contain signature field');+ });+});++// ---------------------------------------------------------------------------+// 5. Verify valid signature+// ---------------------------------------------------------------------------++describe('RvfaVerifier.verifyAppliance', () => {+ it('returns valid=true for a correctly signed file', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const verifier = new RvfaVerifier(kp.publicKey);+ const rvfaPath = writeTestRvfa();++ await signer.signAppliance(rvfaPath, 'publisher-name');++ const result = await verifier.verifyAppliance(rvfaPath);+ assert.ok(result.valid, `Expected valid but got errors: ${result.errors.join(', ')}`);+ assert.equal(result.signerFingerprint, kp.fingerprint);+ assert.equal(result.signedBy, 'publisher-name');+ assert.equal(result.errors.length, 0);+ });+});++// ---------------------------------------------------------------------------+// 6. Verify tampered data+// ---------------------------------------------------------------------------++describe('Tamper detection', () => {+ it('returns valid=false when section data is modified after signing', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const verifier = new RvfaVerifier(kp.publicKey);+ const rvfaPath = writeTestRvfa();++ await signer.signAppliance(rvfaPath);++ // Read the signed file and tamper with section data+ const signedBuf = readFileSync(rvfaPath);+ const tampered = Buffer.from(signedBuf);+ // Tamper with a byte near the end (in section data area, before footer)+ const tamperOffset = tampered.length - 40; // before the 32-byte SHA256 footer+ if (tamperOffset > 0) {+ tampered[tamperOffset] ^= 0xFF;+ }+ writeFileSync(rvfaPath, tampered);++ const result = await verifier.verifyAppliance(rvfaPath);+ assert.ok(!result.valid, 'Tampered file should fail verification');+ assert.ok(result.errors.length > 0);+ });++ it('returns valid=false when header is modified after signing', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const verifier = new RvfaVerifier(kp.publicKey);+ const rvfaPath = writeTestRvfa();++ await signer.signAppliance(rvfaPath);++ // Read the signed file, modify the header name+ const signedBuf = readFileSync(rvfaPath);+ const headerLen = signedBuf.readUInt32LE(8);+ const headerJson = signedBuf.subarray(12, 12 + headerLen).toString('utf-8');+ const header = JSON.parse(headerJson);+ header.name = 'tampered-name';++ const newHeaderJson = Buffer.from(JSON.stringify(header), 'utf-8');+ const preamble = Buffer.alloc(12);+ signedBuf.copy(preamble, 0, 0, 8);+ preamble.writeUInt32LE(newHeaderJson.length, 8);++ const rebuilt = Buffer.concat([+ preamble,+ newHeaderJson,+ signedBuf.subarray(12 + headerLen),+ ]);+ writeFileSync(rvfaPath, rebuilt);++ const result = await verifier.verifyAppliance(rvfaPath);+ assert.ok(!result.valid, 'Modified header should fail verification');+ });+});++// ---------------------------------------------------------------------------+// 7. Verify missing signature+// ---------------------------------------------------------------------------++describe('Missing signature', () => {+ it('returns valid=false with appropriate error for unsigned RVFA', async () => {+ const kp = await generateKeyPair();+ const verifier = new RvfaVerifier(kp.publicKey);+ const rvfaPath = writeTestRvfa();++ const result = await verifier.verifyAppliance(rvfaPath);+ assert.ok(!result.valid);+ assert.ok(+ result.errors.some((e) => e.includes('No signature') || e.includes('signature')),+ `Expected signature-related error, got: ${result.errors.join(', ')}`,+ );+ });+});++// ---------------------------------------------------------------------------+// 8. Sign patch (detached)+// ---------------------------------------------------------------------------++describe('RvfaSigner.signPatch / RvfaVerifier.verifyPatch', () => {+ it('signs arbitrary data and verifies with detached signature', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const verifier = new RvfaVerifier(kp.publicKey);++ const patchData = Buffer.from('this-is-a-patch-payload-for-signing');+ const signature = await signer.signPatch(patchData);++ assert.equal(typeof signature, 'string');+ assert.ok(signature.length > 0);++ const valid = await verifier.verifyPatch(patchData, signature);+ assert.ok(valid, 'Detached patch signature should verify');+ });++ it('detached signature fails for tampered data', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);+ const verifier = new RvfaVerifier(kp.publicKey);++ const patchData = Buffer.from('original-patch-data');+ const signature = await signer.signPatch(patchData);++ const tampered = Buffer.from('tampered-patch-data');+ const valid = await verifier.verifyPatch(tampered, signature);+ assert.ok(!valid, 'Tampered data should fail verification');+ });++ it('signSections signs a 32-byte footer hash and returns hex signature', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);++ const footerHash = Buffer.alloc(32, 0xAB);+ const signature = await signer.signSections(footerHash);++ assert.equal(typeof signature, 'string');+ assert.ok(signature.length > 0);+ // signSections signs the raw hash directly (no re-hash),+ // so we verify manually using Node.js crypto+ const { verify: edVerify, createPublicKey } = await import('node:crypto');+ const pubKeyObj = createPublicKey({+ key: kp.publicKey,+ format: 'pem',+ type: 'spki',+ });+ const valid = edVerify(null, footerHash, pubKeyObj, Buffer.from(signature, 'hex'));+ assert.ok(valid, 'Signature over raw footer hash should verify');+ });++ it('signSections rejects non-32-byte input', async () => {+ const kp = await generateKeyPair();+ const signer = new RvfaSigner(kp.privateKey);++ await assert.rejects(+ () => signer.signSections(Buffer.alloc(16)),+ /32 bytes/,+ );+ });+});++// ---------------------------------------------------------------------------+// 9. Canonical JSON+// ---------------------------------------------------------------------------++describe('Canonical JSON (deterministic signing)', () => {+ it('signing produces the same signature regardless of header key order', async () => {+ const kp = await generateKeyPair();++ // Create two RVFA files with the same content+ const rvfaPath1 = writeTestRvfa('canon-test');+ const rvfaPath2 = writeTestRvfa('canon-test');++ // Sign both with the same key+ const signer = new RvfaSigner(kp.privateKey);+ const sig1 = await signer.signAppliance(rvfaPath1);+ const sig2 = await signer.signAppliance(rvfaPath2);++ // Both should verify successfully+ const verifier = new RvfaVerifier(kp.publicKey);+ const result1 = await verifier.verifyAppliance(rvfaPath1);+ const result2 = await verifier.verifyAppliance(rvfaPath2);++ assert.ok(result1.valid, 'First file should verify');+ assert.ok(result2.valid, 'Second file should verify');+ });+});++// ---------------------------------------------------------------------------+// 10. Re-sign+// ---------------------------------------------------------------------------++describe('Re-signing', () => {+ it('re-signing replaces the old signature cleanly', async () => {+ const kp1 = await generateKeyPair();+ const kp2 = await generateKeyPair();+ const rvfaPath = writeTestRvfa();++ // Sign with first key+ const signer1 = new RvfaSigner(kp1.privateKey);+ await signer1.signAppliance(rvfaPath, 'publisher-one');++ // Verify with first key+ const verifier1 = new RvfaVerifier(kp1.publicKey);+ const result1 = await verifier1.verifyAppliance(rvfaPath);+ assert.ok(result1.valid, 'First signature should verify');++ // Re-sign with second key+ const signer2 = new RvfaSigner(kp2.privateKey);+ await signer2.signAppliance(rvfaPath, 'publisher-two');++ // Verify with second key should pass+ const verifier2 = new RvfaVerifier(kp2.publicKey);+ const result2 = await verifier2.verifyAppliance(rvfaPath);+ assert.ok(result2.valid, 'Re-signed file should verify with new key');+ assert.equal(result2.signedBy, 'publisher-two');++ // Verify with first key should fail+ const result3 = await verifier1.verifyAppliance(rvfaPath);+ assert.ok(!result3.valid, 'Old key should no longer verify');+ });++ it('re-signed file still reads as valid RVFA and verifies', async () => {+ const kp = await generateKeyPair();+ const rvfaPath = writeTestRvfa();++ const signer = new RvfaSigner(kp.privateKey);+ await signer.signAppliance(rvfaPath);+ // Re-sign+ const sigMeta = await signer.signAppliance(rvfaPath);++ assert.equal(sigMeta.algorithm, 'ed25519');+ assert.equal(sigMeta.scope, 'full');++ // The re-signed file should still verify with the same key+ const verifier = new RvfaVerifier(kp.publicKey);+ const result = await verifier.verifyAppliance(rvfaPath);+ assert.ok(result.valid, `Re-signed file should verify: ${result.errors.join(', ')}`);+ });+});