stellavault 0.1.0

package/packages/core/src/federation/node.ts

@@ -0,0 +1,235 @@
+// Design Ref: §4 — FederationNode (Hyperswarm P2P)
+// Plan SC: SC1 (2노드 연결), SC5 (오프라인 정상)
+
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { getOrCreateIdentity, type NodeIdentity } from './identity.js';
+import type { PeerInfo, FederationMessage } from './types.js';
+
+const FEDERATION_TOPIC = createHash('sha256').update('stellavault-federation-v1').digest();
+
+export class FederationNode extends EventEmitter {
+  private swarm: any = null;
+  private identity: NodeIdentity;
+  private peers = new Map<string, { info: PeerInfo; conn: any }>();
+  private running = false;
+  private documentCount = 0;
+  private topTopics: string[] = [];
+
+  constructor(displayName?: string) {
+    super();
+    this.identity = getOrCreateIdentity(displayName);
+  }
+
+  get peerId(): string { return this.identity.peerId; }
+  get displayName(): string { return this.identity.displayName; }
+  get peerCount(): number { return this.peers.size; }
+  get isRunning(): boolean { return this.running; }
+
+  setLocalStats(documentCount: number, topTopics: string[]) {
+    this.documentCount = documentCount;
+    this.topTopics = topTopics.slice(0, 5);
+  }
+
+  // Design Ref: §4 — join()
+  async join(): Promise<void> {
+    if (this.running) return;
+
+    const Hyperswarm = (await import('hyperswarm')).default;
+    this.swarm = new Hyperswarm({ maxPeers: 50 });
+
+    this.swarm.on('connection', (conn: any, _info: any) => {
+      this.handleConnection(conn);
+    });
+
+    const discovery = this.swarm.join(FEDERATION_TOPIC, { server: true, client: true });
+    await discovery.flushed();
+
+    this.running = true;
+    this.emit('joined', { peerId: this.peerId, topic: FEDERATION_TOPIC.toString('hex').slice(0, 16) });
+  }
+
+  // Design Ref: §4 — joinDirect() 수동 IP 폴백
+  async joinDirect(host: string, port: number): Promise<void> {
+    const net = await import('node:net');
+    const conn = net.connect(port, host);
+
+    await new Promise<void>((resolve, reject) => {
+      conn.on('connect', () => {
+        this.handleConnection(conn);
+        resolve();
+      });
+      conn.on('error', reject);
+      setTimeout(() => reject(new Error('Connection timeout')), 15000);
+    });
+
+    if (!this.running) this.running = true;
+  }
+
+  async leave(): Promise<void> {
+    if (!this.running) return;
+
+    for (const [, peer] of this.peers) {
+      try {
+        this.sendMessage(peer.conn, { type: 'leave', peerId: this.peerId });
+        peer.conn.end();
+      } catch { /* ignore */ }
+    }
+
+    this.peers.clear();
+    await this.swarm?.destroy();
+    this.swarm = null;
+    this.running = false;
+    this.emit('left');
+  }
+
+  getPeers(): PeerInfo[] {
+    return [...this.peers.values()].map(p => p.info);
+  }
+
+  // 피어에게 검색 쿼리 전송 (FederatedSearch에서 사용)
+  sendSearchQuery(peerId: string, queryId: string, embedding: number[], limit: number): void {
+    const peer = this.peers.get(peerId);
+    if (!peer) return;
+    this.sendMessage(peer.conn, { type: 'search_query', queryId, embedding, limit });
+  }
+
+  // 피어에게 검색 결과 응답 (FederatedSearch에서 사용)
+  sendSearchResult(peerId: string, queryId: string, results: Array<{ title: string; similarity: number; snippet: string }>): void {
+    const peer = this.peers.get(peerId);
+    if (!peer) return;
+    this.sendMessage(peer.conn, { type: 'search_result', queryId, results });
+  }
+
+  // --- Private ---
+
+  private handleConnection(conn: any) {
+    // 핸드셰이크 전송
+    this.sendMessage(conn, {
+      type: 'handshake',
+      peerId: this.peerId,
+      displayName: this.identity.displayName,
+      version: '0.1.0',
+      documentCount: this.documentCount,
+      topTopics: this.topTopics,
+    });
+
+    let buffer = '';
+    const MAX_BUFFER = 1024 * 1024; // HIGH-04: 1MB 버퍼 제한 (OOM 방지)
+    const MAX_MESSAGE = 64 * 1024;  // 개별 메시지 64KB 제한
+
+    conn.on('data', (data: Buffer) => {
+      buffer += data.toString();
+
+      // 버퍼 크기 초과 시 연결 종료
+      if (buffer.length > MAX_BUFFER) {
+        console.error('Federation: buffer overflow from peer, disconnecting');
+        buffer = '';
+        conn.end();
+        return;
+      }
+
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        if (line.length > MAX_MESSAGE) continue; // 초대형 메시지 무시
+        try {
+          const msg: FederationMessage = JSON.parse(line);
+          this.handleMessage(conn, msg);
+        } catch { /* malformed — ignore */ }
+      }
+    });
+
+    conn.on('close', () => {
+      for (const [peerId, peer] of this.peers) {
+        if (peer.conn === conn) {
+          this.peers.delete(peerId);
+          this.emit('peer_left', { peerId });
+          break;
+        }
+      }
+    });
+
+    conn.on('error', () => { /* swallow */ });
+  }
+
+  // MED: 메시지 스키마 기본 검증
+  private validateMessage(msg: any): boolean {
+    if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') return false;
+    if (msg.type === 'handshake' && (typeof msg.peerId !== 'string' || typeof msg.displayName !== 'string')) return false;
+    if (msg.type === 'search_query' && (!Array.isArray(msg.embedding) || msg.embedding.length !== 384)) return false;
+    if (msg.type === 'search_result' && !Array.isArray(msg.results)) return false;
+    return true;
+  }
+
+  private handleMessage(conn: any, msg: FederationMessage) {
+    if (!this.validateMessage(msg)) return; // 스키마 불일치 메시지 무시
+
+    switch (msg.type) {
+      case 'handshake': {
+        // MED: displayName 길이 제한
+        const safeName = (msg.displayName ?? '').slice(0, 50);
+        const peerInfo: PeerInfo = {
+          peerId: msg.peerId,
+          displayName: safeName,
+          documentCount: Math.min(msg.documentCount ?? 0, 1000000), // 합리적 상한
+          topTopics: (msg.topTopics ?? []).slice(0, 10),
+          joinedAt: new Date().toISOString(),
+          lastSeen: new Date().toISOString(),
+        };
+        this.peers.set(msg.peerId, { info: peerInfo, conn });
+        this.emit('peer_joined', peerInfo);
+        break;
+      }
+
+      case 'search_query': {
+        // Design Ref: §5 — 검색 요청 수신
+        this.emit('search_request', {
+          peerId: msg.queryId, // queryId를 추적용으로 사용
+          queryId: msg.queryId,
+          embedding: msg.embedding,
+          limit: msg.limit,
+          // respond 함수: 호출 측에서 사용
+          respondTo: (() => {
+            // 어느 피어가 보냈는지 찾기
+            for (const [pid, peer] of this.peers) {
+              if (peer.conn === conn) return pid;
+            }
+            return null;
+          })(),
+        });
+        break;
+      }
+
+      case 'search_result': {
+        // FederatedSearch가 이벤트로 수신
+        this.emit('search_response', {
+          queryId: msg.queryId,
+          results: msg.results,
+          peerId: (() => {
+            for (const [pid, peer] of this.peers) {
+              if (peer.conn === conn) return pid;
+            }
+            return 'unknown';
+          })(),
+        });
+        break;
+      }
+
+      case 'leave': {
+        this.peers.delete(msg.peerId);
+        this.emit('peer_left', { peerId: msg.peerId });
+        break;
+      }
+    }
+  }
+
+  // Design Ref: §7 — JSON + newline delimiter
+  private sendMessage(conn: any, msg: FederationMessage) {
+    try {
+      conn.write(JSON.stringify(msg) + '\n');
+    } catch { /* connection may be closed */ }
+  }
+}

package/packages/core/src/federation/privacy.ts

@@ -0,0 +1,52 @@
+// Federation Phase 2: Differential Privacy
+// 임베딩 벡터에 노이즈를 추가하여 원문 복원 방지
+
+import { randomBytes } from 'node:crypto';
+
+export interface DPConfig {
+  epsilon: number;    // 프라이버시 예산 (낮을수록 더 안전, 기본 1.0)
+  enabled: boolean;
+}
+
+const DEFAULT_DP: DPConfig = { epsilon: 1.0, enabled: true };
+
+// 가우시안 노이즈 생성 (Box-Muller 변환)
+function gaussianNoise(): number {
+  const u1 = Math.max(1e-10, Math.random());
+  const u2 = Math.random();
+  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+
+// 임베딩 벡터에 Differential Privacy 노이즈 추가
+export function addDPNoise(embedding: number[], config: DPConfig = DEFAULT_DP): number[] {
+  if (!config.enabled) return embedding;
+
+  const sensitivity = 1.0; // L2 sensitivity (normalized embeddings)
+  const sigma = sensitivity / config.epsilon;
+
+  return embedding.map(v => v + gaussianNoise() * sigma);
+}
+
+// 노이즈 추가 후 L2 정규화 (코사인 유사도 유지)
+export function addDPNoiseNormalized(embedding: number[], config: DPConfig = DEFAULT_DP): number[] {
+  const noisy = addDPNoise(embedding, config);
+
+  // L2 정규화
+  let norm = 0;
+  for (const v of noisy) norm += v * v;
+  norm = Math.sqrt(norm);
+  if (norm === 0) return noisy;
+
+  return noisy.map(v => v / norm);
+}
+
+// 스니펫에 DP 적용 (단어 단위 마스킹)
+export function maskSnippet(snippet: string, maskRate = 0.3): string {
+  const words = snippet.split(/\s+/);
+  return words.map(w => {
+    if (Math.random() < maskRate && w.length > 2) {
+      return w[0] + '***';
+    }
+    return w;
+  }).join(' ');
+}

package/packages/core/src/federation/reputation.ts

@@ -0,0 +1,202 @@
+// Federation: Node Reputation System
+// 자동 평판 점수 — trust + consistency + freshness + consensus + history
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { getTrustLevel } from './trust.js';
+
+export interface ReputationRecord {
+  peerId: string;
+  displayName: string;
+
+  // 수동 (Web of Trust)
+  trustBase: number;           // vouch=30, neutral=0, block=-100
+
+  // 자동: 결과 일관성
+  consistencyScore: number;    // 0-25, 다른 노드들과 결과 유사도
+  consistencySamples: number;  // 측정 횟수
+
+  // 자동: 활동 빈도
+  freshnessScore: number;      // 0-15, 최근 활동
+  lastSeen: string;
+  totalInteractions: number;
+
+  // 자동: 합의
+  consensusScore: number;      // 0-20, 같은 쿼리에 다른 노드와 동일 결과
+  consensusSamples: number;
+
+  // 자동: 유용성 피드백
+  historyScore: number;        // 0-10, 사용자 피드백 (결과 클릭율 등)
+  helpfulCount: number;
+  unhelpfulCount: number;
+
+  updatedAt: string;
+}
+
+const REP_FILE = join(homedir(), '.stellavault', 'federation', 'reputation.json');
+
+function loadRepDb(): Map<string, ReputationRecord> {
+  if (!existsSync(REP_FILE)) return new Map();
+  const records = JSON.parse(readFileSync(REP_FILE, 'utf-8')) as ReputationRecord[];
+  return new Map(records.map(r => [r.peerId, r]));
+}
+
+function saveRepDb(db: Map<string, ReputationRecord>): void {
+  mkdirSync(join(homedir(), '.stellavault', 'federation'), { recursive: true });
+  writeFileSync(REP_FILE, JSON.stringify([...db.values()], null, 2), 'utf-8');
+}
+
+function getOrCreateRecord(peerId: string, displayName = ''): ReputationRecord {
+  const db = loadRepDb();
+  if (db.has(peerId)) return db.get(peerId)!;
+  return {
+    peerId, displayName,
+    trustBase: 0,
+    consistencyScore: 0, consistencySamples: 0,
+    freshnessScore: 0, lastSeen: new Date().toISOString(), totalInteractions: 0,
+    consensusScore: 0, consensusSamples: 0,
+    historyScore: 0, helpfulCount: 0, unhelpfulCount: 0,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+// 종합 평판 점수 계산 (0-100)
+export function computeReputation(peerId: string): number {
+  const rec = getOrCreateRecord(peerId);
+
+  // 수동 신뢰 기반
+  const trustLevel = getTrustLevel(peerId);
+  const trustBase = trustLevel === 'vouched' ? 30 : trustLevel === 'blocked' ? -100 : 0;
+
+  // blocked이면 즉시 0
+  if (trustBase <= -100) return 0;
+
+  const score = Math.max(0, Math.min(100,
+    trustBase +
+    rec.consistencyScore +
+    rec.freshnessScore +
+    rec.consensusScore +
+    rec.historyScore +
+    // 새 노드 보너스 (상호작용 적으면 중립 시작)
+    (rec.totalInteractions < 5 ? 40 : 0)
+  ));
+
+  return Math.round(score);
+}
+
+// 검색 결과에 합의 검증
+export function verifyConsensus(
+  queryId: string,
+  allResults: Array<{ peerId: string; title: string; similarity: number }>,
+): Map<string, number> {
+  // 같은 제목을 반환한 노드가 많을수록 → 합의 높음
+  const titleCounts = new Map<string, number>();
+  for (const r of allResults) {
+    titleCounts.set(r.title, (titleCounts.get(r.title) ?? 0) + 1);
+  }
+
+  const totalPeers = new Set(allResults.map(r => r.peerId)).size;
+  const consensusBoost = new Map<string, number>();
+
+  for (const r of allResults) {
+    const count = titleCounts.get(r.title) ?? 1;
+    // 여러 노드가 같은 결과 → 신뢰도 부스트
+    const boost = count > 1 ? Math.min((count / totalPeers) * 20, 20) : 0;
+    const current = consensusBoost.get(r.peerId) ?? 0;
+    consensusBoost.set(r.peerId, Math.max(current, boost));
+  }
+
+  return consensusBoost;
+}
+
+// 노드 상호작용 기록 (검색 응답 받을 때마다)
+export function recordInteraction(peerId: string, displayName: string): void {
+  const db = loadRepDb();
+  const rec = getOrCreateRecord(peerId, displayName);
+
+  rec.totalInteractions++;
+  rec.lastSeen = new Date().toISOString();
+  rec.displayName = displayName || rec.displayName;
+
+  // Freshness: 최근 7일 이내 활동이면 만점
+  const daysSinceLastSeen = (Date.now() - new Date(rec.lastSeen).getTime()) / 86400000;
+  rec.freshnessScore = daysSinceLastSeen < 1 ? 15 : daysSinceLastSeen < 7 ? 10 : daysSinceLastSeen < 30 ? 5 : 0;
+
+  rec.updatedAt = new Date().toISOString();
+  db.set(peerId, rec);
+  saveRepDb(db);
+}
+
+// 결과 일관성 업데이트 (다른 노드와 비교)
+export function recordConsistency(peerId: string, matchRate: number): void {
+  const db = loadRepDb();
+  const rec = getOrCreateRecord(peerId);
+
+  rec.consistencySamples++;
+  // 이동 평균
+  rec.consistencyScore = Math.round(
+    (rec.consistencyScore * (rec.consistencySamples - 1) + matchRate * 25) / rec.consistencySamples
+  );
+
+  rec.updatedAt = new Date().toISOString();
+  db.set(peerId, rec);
+  saveRepDb(db);
+}
+
+// 사용자 피드백 (결과가 유용했는지)
+export function recordFeedback(peerId: string, helpful: boolean): void {
+  const db = loadRepDb();
+  const rec = getOrCreateRecord(peerId);
+
+  if (helpful) rec.helpfulCount++;
+  else rec.unhelpfulCount++;
+
+  const total = rec.helpfulCount + rec.unhelpfulCount;
+  rec.historyScore = total > 0 ? Math.round((rec.helpfulCount / total) * 10) : 0;
+
+  rec.updatedAt = new Date().toISOString();
+  db.set(peerId, rec);
+  saveRepDb(db);
+}
+
+// 합의 점수 업데이트
+export function recordConsensus(peerId: string, consensusBoost: number): void {
+  const db = loadRepDb();
+  const rec = getOrCreateRecord(peerId);
+
+  rec.consensusSamples++;
+  rec.consensusScore = Math.round(
+    (rec.consensusScore * (rec.consensusSamples - 1) + consensusBoost) / rec.consensusSamples
+  );
+
+  rec.updatedAt = new Date().toISOString();
+  db.set(peerId, rec);
+  saveRepDb(db);
+}
+
+// 평판 목록 조회
+export function getReputationBoard(): Array<ReputationRecord & { reputation: number }> {
+  const db = loadRepDb();
+  return [...db.values()]
+    .map(r => ({ ...r, reputation: computeReputation(r.peerId) }))
+    .sort((a, b) => b.reputation - a.reputation);
+}
+
+// 검색 결과 필터 + 정렬 (평판 가중)
+export function filterByReputation<T extends { peerId: string; similarity: number }>(
+  results: T[],
+  minReputation = 10,
+): (T & { adjustedScore: number; reputation: number })[] {
+  return results
+    .map(r => {
+      const rep = computeReputation(r.peerId);
+      // blocked 노드 필터링
+      if (rep === 0) return null;
+      // 평판 가중 점수: similarity * 0.7 + reputation/100 * 0.3
+      const adjustedScore = r.similarity * 0.7 + (rep / 100) * 0.3;
+      return { ...r, adjustedScore, reputation: rep };
+    })
+    .filter((r): r is NonNullable<typeof r> => r !== null && r.reputation >= minReputation)
+    .sort((a, b) => b.adjustedScore - a.adjustedScore);
+}

package/packages/core/src/federation/search.ts

@@ -0,0 +1,129 @@
+// Design Ref: §5 — FederatedSearch (피어 검색 + 결과 병합)
+// Plan SC: SC2 (연합 검색), SC3 (원문 비노출), SC4 (3초 이내)
+
+import { randomUUID } from 'node:crypto';
+import type { FederationNode } from './node.js';
+import type { VectorStore } from '../store/types.js';
+import type { Embedder } from '../indexer/embedder.js';
+import type { FederatedSearchResult } from './types.js';
+import { maskSnippet } from './privacy.js';
+import { isDocumentShareable, sanitizeSnippet } from './sharing.js';
+
+export interface FederatedSearchOptions {
+  limit?: number;
+  timeout?: number; // ms, default 5000
+}
+
+export class FederatedSearch {
+  private additionalStores: VectorStore[] = [];
+
+  constructor(
+    private node: FederationNode,
+    private store: VectorStore,
+    private embedder: Embedder,
+  ) {}
+
+  // Multi-vault: 추가 store 등록 (Federation 검색 응답 시 전체 vault 검색)
+  addStore(store: VectorStore): void {
+    this.additionalStores.push(store);
+  }
+
+  // Design Ref: §5 — search() 요청 측
+  async search(query: string, options: FederatedSearchOptions = {}): Promise<FederatedSearchResult[]> {
+    const { limit = 5, timeout = 5000 } = options;
+    const peers = this.node.getPeers();
+
+    if (peers.length === 0) {
+      return [];
+    }
+
+    // 1. 쿼리 임베딩 생성
+    const embedding = await this.embedder.embed(query);
+    const queryId = randomUUID().slice(0, 8);
+
+    // 2. 모든 피어에 병렬 전송 + 응답 대기
+    const results: FederatedSearchResult[] = [];
+    const peerMap = new Map(peers.map(p => [p.peerId, p.displayName]));
+
+    const responsePromises = peers.map((peer) => {
+      return new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, timeout);
+
+        const handler = (data: { queryId: string; results: any[]; peerId: string }) => {
+          if (data.queryId !== queryId) return;
+
+          for (const r of data.results) {
+            results.push({
+              title: r.title,
+              similarity: r.similarity,
+              snippet: r.snippet,
+              peerId: peer.peerId,
+              peerName: peer.displayName,
+            });
+          }
+
+          clearTimeout(timer);
+          this.node.removeListener('search_response', handler);
+          resolve();
+        };
+
+        this.node.on('search_response', handler);
+
+        // 쿼리 전송
+        this.node.sendSearchQuery(peer.peerId, queryId, Array.from(embedding), limit);
+      });
+    });
+
+    await Promise.allSettled(responsePromises);
+
+    // 3. 결과 병합 — similarity 내림차순
+    return results
+      .sort((a, b) => b.similarity - a.similarity)
+      .slice(0, limit);
+  }
+
+  // Design Ref: §5 — startResponder() 피어 요청 수신 측
+  startResponder(): void {
+    this.node.on('search_request', async (req: {
+      queryId: string;
+      embedding: number[];
+      limit: number;
+      respondTo: string | null;
+    }) => {
+      if (!req.respondTo) return;
+
+      try {
+        // 받은 임베딩으로 모든 로컬 vault DB 검색 (multi-vault)
+        const allStores = [this.store, ...this.additionalStores];
+        const allScored = await Promise.all(
+          allStores.map(s => s.searchSemantic(req.embedding, req.limit).catch(() => []))
+        );
+        const scored = allScored.flat().sort((a, b) => b.score - a.score).slice(0, req.limit);
+
+        // Plan SC: SC3 — 원문 비노출. 제목+유사도+50자만.
+        const safe: Array<{ title: string; similarity: number; snippet: string }> = [];
+        for (const s of scored) {
+          const chunk = await this.store.getChunk(s.chunkId);
+          if (!chunk) continue;
+          // 청크의 documentId에서 문서 제목 가져오기
+          const doc = await this.store.getDocument(chunk.documentId);
+          if (!doc) continue;
+
+          // Sharing filter: 비공개 문서는 검색 결과에서 제외
+          if (!isDocumentShareable({ tags: doc.tags, filePath: doc.filePath, id: doc.id, content: doc.content })) continue;
+
+          safe.push({
+            title: doc.title ?? chunk.heading ?? 'Untitled',
+            similarity: Math.round(s.score * 1000) / 1000,
+            snippet: sanitizeSnippet(maskSnippet(chunk.content.slice(0, 50), 0.2)),
+          });
+        }
+
+        this.node.sendSearchResult(req.respondTo, req.queryId, safe);
+      } catch (err) {
+        // 검색 실패 시 빈 결과 반환
+        this.node.sendSearchResult(req.respondTo, req.queryId, []);
+      }
+    });
+  }
+}