stellavault 0.2.0 → 0.2.1

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

@@ -1,235 +0,0 @@
-// 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

@@ -1,52 +0,0 @@
-// 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

@@ -1,202 +0,0 @@
-// 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

@@ -1,129 +0,0 @@
-// 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, []);
-      }
-    });
-  }
-}