@n2world/orchestrator 1.1.0

package/dist/mcts-prior.js

@@ -0,0 +1,170 @@
+"use strict";
+// ============================================================================
+// P4 — 임베딩 가중 사전확률 P(s,a) for MCTS PUCT (계획서 v2.4 §7 P4 · 헌법 §3)
+// ----------------------------------------------------------------------------
+// P1(경계-staleness 임베딩)·P2(지식 그래프) 신호를 MCTS 사전확률 P(s,a)에 가중으로 주입한다.
+// PUCT: a* = argmax_a[ Q + c_puct·P(s,a)·√(ΣN)/(1+N) ] 의 P 항에 반영.
+//
+// 정직 고지(제1계명·다축 정신):
+//  - P(s,a)는 P1 `personalizedPrior`(임베딩 코사인 softmax)를 재사용하고, P2 그래프 연결로 부스트한다.
+//  - 사전확률의 이득은 **신호 품질에 의존**한다 — 컨텍스트-유사도가 진짜 가치와 상관일 때만 탐색을 줄인다.
+//    오도하는 신호(반-상관)에선 이득이 없거나 해가 될 수 있음을 함께 측정해 정직히 보고한다(과대표기 금지).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embeddingWeightedPrior = embeddingWeightedPrior;
+exports.uniformPrior = uniformPrior;
+exports.puctSelect = puctSelect;
+exports.runPuctSearch = runPuctSearch;
+exports.comparePriorEfficiency = comparePriorEfficiency;
+exports.lcg = lcg;
+const personalization_1 = require("./personalization");
+const EPS = 1e-12;
+/**
+ * P1 임베딩 + (옵션)P2 그래프로 사전확률 P(s,a)를 만든다(합=1).
+ * graph/graphAnchors 가 주어지면, 앵커 노드와 참조/의존으로 연결된 액션의 prior 를 곱셈 부스트 후 재정규화.
+ */
+function embeddingWeightedPrior(actions, context, opts = {}) {
+    if (actions.length === 0)
+        return [];
+    const candidates = actions.map((a) => ({ id: a.id, content: a.content }));
+    // P1 재사용: 임베딩 코사인 softmax 사전확률.
+    const base = (0, personalization_1.personalizedPrior)(candidates, context, { enabled: true, temperature: opts.temperature });
+    const weight = new Map(base.map((b) => [b.id, b.weight]));
+    // P2 그래프 부스트(옵션): 앵커와 reference/dependency 로 연결된 액션을 강화.
+    if (opts.graph && opts.graphAnchors && opts.graphAnchors.length > 0 && (opts.graphBoost ?? 1) !== 1) {
+        const boost = opts.graphBoost ?? 1.5;
+        const anchors = new Set(opts.graphAnchors);
+        const connected = new Set();
+        for (const e of opts.graph.edges) {
+            if (e.type === 'similarity')
+                continue;
+            if (anchors.has(e.source))
+                connected.add(e.target);
+            if (anchors.has(e.target))
+                connected.add(e.source);
+        }
+        for (const id of connected) {
+            if (weight.has(id))
+                weight.set(id, (weight.get(id) ?? 0) * boost);
+        }
+    }
+    const z = [...weight.values()].reduce((a, b) => a + b, 0);
+    if (z <= EPS) {
+        const u = 1 / actions.length;
+        return actions.map((a) => ({ id: a.id, prior: u }));
+    }
+    return actions.map((a) => ({ id: a.id, prior: (weight.get(a.id) ?? 0) / z }));
+}
+/** 균등 사전확률(비교군 baseline). */
+function uniformPrior(actions) {
+    const u = actions.length ? 1 / actions.length : 0;
+    return actions.map((a) => ({ id: a.id, prior: u }));
+}
+/** 식(1) PUCT 선택: argmax[ Q + c_puct·P·√(ΣN)/(1+n) ]. */
+function puctSelect(stats, cPuct) {
+    let totalN = 0;
+    for (const s of stats)
+        totalN += s.n;
+    const sqrtSum = Math.sqrt(totalN);
+    let best = stats[0];
+    let bestScore = -Infinity;
+    for (const s of stats) {
+        const q = s.n > 0 ? s.w / s.n : 0;
+        const u = cPuct * s.prior * (sqrtSum / (1 + s.n));
+        const score = q + u;
+        if (score > bestScore) {
+            bestScore = score;
+            best = s;
+        }
+    }
+    return best;
+}
+/**
+ * 사전확률 priors 로 PUCT 탐색을 sims 회 돌리고 효율 지표를 반환한다.
+ * 보상 = trueValue[선택] + 가우시안 잡음(외부 오라클). target = trueValue 최대 액션.
+ * @param rnd 결정적 난수(시드 고정) — 재현성.
+ */
+function runPuctSearch(actions, priors, trueValue, sims, cPuct, rnd, noiseSd = 0.1) {
+    const priorMap = new Map(priors.map((p) => [p.id, p.prior]));
+    const stats = actions.map((a) => ({ id: a.id, n: 0, w: 0, prior: priorMap.get(a.id) ?? 0 }));
+    const maxTrue = Math.max(...actions.map((a) => trueValue[a.id] ?? 0));
+    const targetId = actions.reduce((best, a) => (trueValue[a.id] ?? 0) > (trueValue[best.id] ?? 0) ? a : best).id;
+    let regret = 0;
+    let simsToConverge = sims + 1;
+    let converged = false;
+    for (let t = 1; t <= sims; t++) {
+        const pick = puctSelect(stats, cPuct);
+        // Box-Muller 잡음.
+        const u1 = Math.max(EPS, rnd());
+        const u2 = rnd();
+        const g = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+        const reward = Math.max(0, Math.min(1, (trueValue[pick.id] ?? 0) + g * noiseSd));
+        pick.w += reward;
+        pick.n += 1;
+        regret += maxTrue - (trueValue[pick.id] ?? 0);
+        if (!converged) {
+            let mostVisited = stats[0];
+            for (const s of stats)
+                if (s.n > mostVisited.n)
+                    mostVisited = s;
+            if (mostVisited.id === targetId) {
+                simsToConverge = t;
+                converged = true;
+            }
+        }
+    }
+    let finalBest = stats[0];
+    for (const s of stats)
+        if (s.n > finalBest.n)
+            finalBest = s;
+    const target = stats.find((s) => s.id === targetId);
+    return {
+        simsToConverge,
+        finalBestId: finalBest.id,
+        targetVisits: target.n,
+        regret: +regret.toFixed(3),
+    };
+}
+/**
+ * 균등 vs 임베딩 사전확률의 PUCT 탐색 효율을 다회 비교한다(결정적 시드).
+ * trueValue 는 호출자가 주는 외부 오라클(임베딩과 독립적으로 정한 진짜 가치).
+ */
+function comparePriorEfficiency(actions, context, trueValue, opts = {}) {
+    const sims = opts.sims ?? 200;
+    const cPuct = opts.cPuct ?? 1.41;
+    const trials = opts.trials ?? 50;
+    const embPriors = embeddingWeightedPrior(actions, context, opts.priorOpts);
+    const uniPriors = uniformPrior(actions);
+    const agg = (priors, baseSeed) => {
+        let sumSims = 0, sumRegret = 0, converged = 0;
+        for (let i = 0; i < trials; i++) {
+            const rnd = lcg(baseSeed + i * 1013904223);
+            const r = runPuctSearch(actions, priors, trueValue, sims, cPuct, rnd);
+            sumSims += r.simsToConverge;
+            sumRegret += r.regret;
+            if (r.simsToConverge <= sims)
+                converged++;
+        }
+        return {
+            simsToConvergeMean: +(sumSims / trials).toFixed(2),
+            regretMean: +(sumRegret / trials).toFixed(2),
+            convergedRate: +(converged / trials).toFixed(3),
+        };
+    };
+    const uniform = agg(uniPriors, (opts.seed ?? 12345) >>> 0);
+    const embedding = agg(embPriors, ((opts.seed ?? 12345) ^ 0x9e3779b9) >>> 0);
+    return {
+        uniform,
+        embedding,
+        simsToConvergeSaved: +(uniform.simsToConvergeMean - embedding.simsToConvergeMean).toFixed(2),
+        trials,
+    };
+}
+/** 결정적 LCG(시드 고정) — 재현 가능한 측정. */
+function lcg(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (1664525 * s + 1013904223) >>> 0;
+        return s / 0xffffffff;
+    };
+}

package/dist/model-router.d.ts

@@ -0,0 +1,51 @@
+import { Tier } from './tier-classifier';
+import { TierGuard, ProviderKind } from './tier-guard';
+export interface ModelSpec {
+    id: string;
+    kind: ProviderKind;
+    /** 1K 토큰당 비용(상대). */
+    costPer1k: number;
+    /** 주입형 호출(테스트/프로덕션 공통 시그니처). */
+    call: (prompt: string) => Promise<{
+        text: string;
+        tokens: number;
+    }>;
+}
+export interface RouteOptions {
+    tier: Tier;
+    /** 계획 가치 v (낮으면 로컬 위임 후보). */
+    v: number;
+    /** Tier-1 외부 송신 동의. */
+    userConsent?: boolean;
+    /** v 기반 위임 활성(ECE 합격 시 true). 미달이면 false → 위임 안 함. */
+    delegationEnabled: boolean;
+    /** v 위임 임계(이하면 로컬). */
+    vDelegateBelow?: number;
+}
+export interface RunReport {
+    text: string;
+    modelId: string;
+    tokens: number;
+    cost: number;
+    failovers: number;
+    /** 태스크 경계에서만 교체됐는가(중간 교체 0이어야 함). */
+    midTaskSwaps: number;
+    trail: string[];
+}
+export declare class ModelRouter {
+    private models;
+    private guard;
+    constructor(models: {
+        frontier: ModelSpec;
+        local: ModelSpec;
+        fallback: ModelSpec;
+    }, guard?: TierGuard);
+    /** Tier·v·가드를 반영해 *이 태스크에 사용할 단일 모델*을 선택(중간 교체 없음). */
+    private select;
+    /**
+     * 한 태스크를 실행. 선택된 모델로 호출하고, 실패 시 **태스크 경계에서** 폴백으로 재시도
+     * (진행 중 교체 아님: 같은 프롬프트를 처음부터 다시). midTaskSwaps는 항상 0.
+     */
+    runTask(prompt: string, opts: RouteOptions): Promise<RunReport>;
+    guardRef(): TierGuard;
+}

package/dist/model-router.js

@@ -0,0 +1,75 @@
+"use strict";
+// ============================================================================
+// v2.5.2 Phase 2 — AdaptiveModelRouting + Failover (비용·안전 우선)
+// ----------------------------------------------------------------------------
+// 계획서 v2.5.2 §6: 모델 3종(프런티어1+로컬1+폴백1)으로 시작. Tier 라우팅 강제,
+// **태스크 중간 교체 금지**(failover는 태스크 경계에서만), v 캘리브레이션 전제 위임.
+//
+// 정직 고지(제1계명): 본 라우터는 *주입형 호출 함수*로 동작(네트워크 비종속·테스트 가능).
+// 실제 제공자 연결은 llm.ts. 비용은 호출 결과로만 집계(가짜 비용 금지).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelRouter = void 0;
+const tier_guard_1 = require("./tier-guard");
+class ModelRouter {
+    models;
+    guard;
+    constructor(models, guard = new tier_guard_1.TierGuard()) {
+        this.models = models;
+        this.guard = guard;
+    }
+    /** Tier·v·가드를 반영해 *이 태스크에 사용할 단일 모델*을 선택(중간 교체 없음). */
+    select(opts) {
+        const { frontier, local, fallback } = this.models;
+        // Tier-0: 무조건 로컬
+        if (opts.tier === 0)
+            return { model: local, reason: 'Tier-0 → 로컬 강제' };
+        // v 위임: 캘리브레이션 합격 + v 낮음 → 로컬(저가)
+        if (opts.delegationEnabled && opts.v <= (opts.vDelegateBelow ?? 0.3)) {
+            return { model: local, reason: `저가치 위임(v=${opts.v})` };
+        }
+        // Tier-1 외부는 동의 필요 — 없으면 로컬 우선
+        if (opts.tier === 1 && !opts.userConsent)
+            return { model: local, reason: 'Tier-1 외부 동의 없음 → 로컬' };
+        return { model: frontier, reason: '프런티어 사용' };
+    }
+    /**
+     * 한 태스크를 실행. 선택된 모델로 호출하고, 실패 시 **태스크 경계에서** 폴백으로 재시도
+     * (진행 중 교체 아님: 같은 프롬프트를 처음부터 다시). midTaskSwaps는 항상 0.
+     */
+    async runTask(prompt, opts) {
+        const trail = [];
+        let failovers = 0;
+        const sel = this.select(opts);
+        // 가드: Tier-0 외부 시도는 차단됨(여기서는 select가 이미 로컬 강제하지만 이중 확인)
+        const gate = this.guard.evaluate({ tier: opts.tier, provider: sel.model.id + (sel.model.kind === 'local' ? '-local' : ''), userConsent: opts.userConsent });
+        trail.push(`select=${sel.model.id}(${sel.reason}); guard=${gate.allowed ? 'allow' : 'block'}`);
+        // 폴백 순서: 선택모델 → fallback (태스크 경계 재시도)
+        const order = [sel.model, this.models.fallback].filter((m, i, arr) => arr.findIndex((x) => x.id === m.id) === i);
+        let lastErr = '';
+        for (const m of order) {
+            // Tier-0면 외부 모델은 건너뜀(가드)
+            if (opts.tier === 0 && m.kind === 'external') {
+                trail.push(`skip ${m.id}: Tier-0 외부 금지`);
+                continue;
+            }
+            try {
+                const r = await m.call(prompt);
+                trail.push(`ok ${m.id} tokens=${r.tokens}`);
+                return {
+                    text: r.text, modelId: m.id, tokens: r.tokens,
+                    cost: +(r.tokens / 1000 * m.costPer1k).toFixed(4),
+                    failovers, midTaskSwaps: 0, trail,
+                };
+            }
+            catch (e) {
+                failovers += 1;
+                lastErr = e?.message || String(e);
+                trail.push(`fail ${m.id}: ${lastErr} → 태스크 경계 폴백`);
+            }
+        }
+        throw new Error(`all models failed: ${lastErr} | trail=${trail.join(' | ')}`);
+    }
+    guardRef() { return this.guard; }
+}
+exports.ModelRouter = ModelRouter;

package/dist/multi-axis-lift.d.ts

@@ -0,0 +1,43 @@
+export interface ArmMetrics {
+    heldOutSuccesses: number;
+    heldOutTotal: number;
+    oracleCalls: number;
+    totalTimeMs: number;
+    redTeamBlocked: number;
+    redTeamTotal: number;
+    badHabitReinforced: number;
+    badHabitOpportunities: number;
+    meanSatisfaction: number | null;
+}
+export interface AxisLift {
+    name: string;
+    on: number;
+    off: number;
+    /** 상대 리프트(양수=ON이 더 좋음). 정의는 축마다 다름(주석 참고). */
+    lift: number;
+    betterIsHigher: boolean;
+    improved: boolean;
+}
+export interface MultiAxisReport {
+    success: AxisLift;
+    efficiency: AxisLift;
+    safety: AxisLift;
+    satisfaction: AxisLift | null;
+    /** ③ 안전이 유의 악화됐는가(거부권 트리거). */
+    safetyRegressed: boolean;
+    /** ① 성공률 차이의 2-비율 z검정. */
+    successPValue: number | null;
+    successSignificant: boolean;
+    /** 최종 판정: 안전 미악화 ∧ 성공률 유의 향상일 때만 리프트 인정. */
+    liftAccepted: boolean;
+    /** 헌법 부칙3: 비유의 시 개인화 기본 OFF. */
+    personalizationDefault: 'on' | 'off';
+    /** 구현강도 상한(정직 — null이어도 일반화 금지). */
+    implementationCap: string;
+    notes: string[];
+}
+/**
+ * 개인화 ON vs OFF 의 4축 리프트를 계산하고 정직 판정을 내린다.
+ * @param implementationNote 현 구현강도 설명(상한 명시에 사용).
+ */
+export declare function computeMultiAxisLift(on: ArmMetrics, off: ArmMetrics, implementationNote?: string): MultiAxisReport;

package/dist/multi-axis-lift.js

@@ -0,0 +1,141 @@
+"use strict";
+// ============================================================================
+// B1 — MultiAxisLift: 개인화 ROI 의 다차원 정직 측정 (계획서 v2.4 §4.1)
+// ----------------------------------------------------------------------------
+// 단일 스칼라 금지(Feynman). 리프트를 4축으로 측정:
+//   ① held-out 성공률(오라클)  ② 효율(오라클 호출/과제)  ③ 안전 퇴행(레드팀·나쁜습관)
+//   ④ 실사용자 만족(베타 라벨)
+// 규칙: ②(속도)가 올라도 ③(안전)이 나빠지면 리프트로 인정하지 않는다(안전 거부권).
+// 비유의 시 개인화 기본 OFF(헌법 부칙3). 결론은 구현강도 상한을 명시한다.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeMultiAxisLift = computeMultiAxisLift;
+const SAFETY_REGRESSION_EPS = 0.02; // 2%p 이상 악화면 거부권
+function rate(num, den) {
+    return den > 0 ? num / den : 0;
+}
+// 표준정규 CDF 근사(Abramowitz-Stegun 7.1.26 기반).
+function normalCdf(x) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(x));
+    const d = 0.3989422804014327 * Math.exp(-(x * x) / 2);
+    const p = d * t * (0.319381530 + t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429))));
+    return x >= 0 ? 1 - p : p;
+}
+/** 2-비율 z검정 양측 p값. 표본/분산이 0이면 null(검정 불가). */
+function twoProportionPValue(s1, n1, s2, n2) {
+    if (n1 <= 0 || n2 <= 0)
+        return null;
+    const p1 = s1 / n1;
+    const p2 = s2 / n2;
+    const pPool = (s1 + s2) / (n1 + n2);
+    const se = Math.sqrt(pPool * (1 - pPool) * (1 / n1 + 1 / n2));
+    if (se === 0)
+        return null;
+    const z = (p1 - p2) / se;
+    return +(2 * (1 - normalCdf(Math.abs(z)))).toFixed(4);
+}
+/** 안전 합성 점수∈[0,1]: 레드팀 차단율과 (1 - 나쁜습관강화율)의 평균(높을수록 안전). */
+function safetyScore(m) {
+    const parts = [];
+    if (m.redTeamTotal > 0)
+        parts.push(rate(m.redTeamBlocked, m.redTeamTotal));
+    if (m.badHabitOpportunities > 0)
+        parts.push(1 - rate(m.badHabitReinforced, m.badHabitOpportunities));
+    if (parts.length === 0)
+        return 1; // 안전 신호 없음 → 중립(악화 아님)
+    return parts.reduce((a, b) => a + b, 0) / parts.length;
+}
+/**
+ * 개인화 ON vs OFF 의 4축 리프트를 계산하고 정직 판정을 내린다.
+ * @param implementationNote 현 구현강도 설명(상한 명시에 사용).
+ */
+function computeMultiAxisLift(on, off, implementationNote = '임베딩 가중 사전확률 + 컨텍스트 주입(얕은 개인화)') {
+    const notes = [];
+    // ① 성공률 (높을수록 좋음)
+    const onSucc = rate(on.heldOutSuccesses, on.heldOutTotal);
+    const offSucc = rate(off.heldOutSuccesses, off.heldOutTotal);
+    const success = {
+        name: 'held-out 성공률(오라클)',
+        on: +onSucc.toFixed(4),
+        off: +offSucc.toFixed(4),
+        lift: +(onSucc - offSucc).toFixed(4),
+        betterIsHigher: true,
+        improved: onSucc > offSucc,
+    };
+    // ② 효율 = 과제당 오라클 호출(낮을수록 좋음). 리프트 = 절감율.
+    const onCalls = rate(on.oracleCalls, on.heldOutTotal);
+    const offCalls = rate(off.oracleCalls, off.heldOutTotal);
+    const efficiency = {
+        name: '효율(과제당 오라클 호출, 낮을수록 좋음)',
+        on: +onCalls.toFixed(4),
+        off: +offCalls.toFixed(4),
+        lift: offCalls > 0 ? +((offCalls - onCalls) / offCalls).toFixed(4) : 0, // 양수=절감
+        betterIsHigher: false,
+        improved: onCalls < offCalls,
+    };
+    // ③ 안전 (높을수록 좋음). 거부권: ON이 OFF보다 EPS 이상 낮으면 악화.
+    const onSafe = safetyScore(on);
+    const offSafe = safetyScore(off);
+    const safety = {
+        name: '안전(레드팀 차단·나쁜습관, 높을수록 좋음)',
+        on: +onSafe.toFixed(4),
+        off: +offSafe.toFixed(4),
+        lift: +(onSafe - offSafe).toFixed(4),
+        betterIsHigher: true,
+        improved: onSafe >= offSafe,
+    };
+    const safetyRegressed = onSafe < offSafe - SAFETY_REGRESSION_EPS;
+    // ④ 만족 (높을수록 좋음). 한쪽이라도 라벨 없으면 null(미측정).
+    let satisfaction = null;
+    if (on.meanSatisfaction !== null && off.meanSatisfaction !== null) {
+        satisfaction = {
+            name: '실사용자 만족(베타 라벨)',
+            on: +on.meanSatisfaction.toFixed(4),
+            off: +off.meanSatisfaction.toFixed(4),
+            lift: +(on.meanSatisfaction - off.meanSatisfaction).toFixed(4),
+            betterIsHigher: true,
+            improved: on.meanSatisfaction > off.meanSatisfaction,
+        };
+    }
+    else {
+        notes.push('④ 만족: 베타 라벨 부재 → (목표; 미측정). 접지 전이므로 만족 축 미반영.');
+    }
+    // 성공률 유의성(2-비율 z검정)
+    const successPValue = twoProportionPValue(on.heldOutSuccesses, on.heldOutTotal, off.heldOutSuccesses, off.heldOutTotal);
+    const successSignificant = successPValue !== null && successPValue < 0.05 && success.improved;
+    // 최종 판정: 안전 거부권 우선. 안전 악화면 속도/성공 향상에도 불인정.
+    let liftAccepted = false;
+    if (safetyRegressed) {
+        notes.push('③ 안전 거부권 발동: 안전 퇴행으로 리프트 불인정(②/① 향상 무관).');
+    }
+    else if (successSignificant) {
+        liftAccepted = true;
+    }
+    else {
+        notes.push('① 성공률 향상이 통계적으로 유의하지 않음(p≥0.05 또는 표본 부족).');
+    }
+    // 헌법 부칙3: 비유의 시 개인화 기본 OFF.
+    const personalizationDefault = liftAccepted ? 'on' : 'off';
+    if (!liftAccepted) {
+        notes.push('헌법 부칙3 적용: 개인화 기본 OFF 로 회귀(폴백).');
+    }
+    // 표본 한계 정직 표기
+    const minN = Math.min(on.heldOutTotal, off.heldOutTotal);
+    if (minN < 30)
+        notes.push(`표본 한계: 최소 arm N=${minN} (<30). 소표본 — 결론은 잠정.`);
+    const implementationCap = `결론은 "현 구현(${implementationNote})에서의 리프트"로 한정한다. ` +
+        `null/비유의여도 개인화 일반의 무용으로 일반화하지 않는다(강한 구현=v3 latent 은 데이터가 정당화할 때 별도 검증).`;
+    return {
+        success,
+        efficiency,
+        safety,
+        satisfaction,
+        safetyRegressed,
+        successPValue,
+        successSignificant,
+        liftAccepted,
+        personalizationDefault,
+        implementationCap,
+        notes,
+    };
+}

package/dist/net-guard.d.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage } from 'http';
+/**
+ * remoteAddress 가 루프백인가. IPv4(127.0.0.0/8)·IPv6(::1)·IPv4-mapped(::ffff:127.x) 포함.
+ * 주의: 호스트명/헤더(X-Forwarded-For 등 *위조 가능*)는 신뢰하지 않는다 — 소켓 주소만.
+ */
+export declare function isLoopbackAddress(addr: string | undefined | null): boolean;
+/** 요청 소켓이 루프백에서 왔는가(전송계층 판정). */
+export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+/**
+ * 토큰 추출: Authorization: Bearer <t> → X-Dashboard-Token 헤더 → ?token= 쿼리.
+ * (EventSource/SSE 는 헤더를 못 실으므로 쿼리 폴백 허용.)
+ */
+export declare function extractBearerToken(req: IncomingMessage): string | undefined;
+/**
+ * H3 — 요청에서 AuthContext 를 *전송계층 기준*으로 구성한다.
+ * loopback 은 소켓 주소로 판정(클라이언트 제공 불리언/헤더 신뢰 금지), token 은 헤더/쿼리에서.
+ * 컴패니언/페어링은 반드시 이 함수로 컨텍스트를 만들어야 위조(loopback:true)를 막는다.
+ */
+export declare function authContextFromRequest(req: IncomingMessage): {
+    token?: string;
+    loopback: boolean;
+};
+/** 길이/내용 모두 timing-safe 비교(불일치 길이도 누설 안 함). */
+export declare function timingSafeEqualStr(a: string | undefined, b: string | undefined): boolean;
+export interface AccessDecision {
+    ok: boolean;
+    reason: string;
+    /** 어떤 근거로 허용됐는가(감사용): 'loopback' | 'token' | '' */
+    via: 'loopback' | 'token' | '';
+}
+/**
+ * 표준 접근 정책(C1):
+ *   - 루프백 요청 → 허용(로컬 신뢰; 단 requireTokenAlways=true면 토큰도 요구).
+ *   - 비루프백 요청 → 유효 토큰 필수(없으면 거부).
+ * token 미설정(서버에 토큰 없음) + 비루프백 → 거부(안전 기본값).
+ */
+export declare function decideAccess(req: IncomingMessage, serverToken: string | undefined, opts?: {
+    requireTokenAlways?: boolean;
+}): AccessDecision;

package/dist/net-guard.js

@@ -0,0 +1,141 @@
+"use strict";
+// ============================================================================
+// 보안 하드닝 공용 — 전송계층 신뢰 판정 (C1 대시보드 / H3 컴패니언·페어링 공용)
+// ----------------------------------------------------------------------------
+// 보안 점검 보고서 v1.0 의 C1(무인증 RCE)·H3(loopback 전송계층 미결선) 대응.
+//   - isLoopbackAddress: req.socket.remoteAddress 로 *실제* 루프백 판정(불리언 신뢰 금지).
+//   - extractBearerToken: Authorization/X-*/?token= 에서 토큰 추출.
+//   - timingSafeEqualStr: 길이 비노출 timing-safe 비교.
+//
+// 정직 고지(제1계명): 본 모듈은 순수 함수(테스트 가능). 효력은 라우팅에서 *실제* 적용해야 발생.
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLoopbackAddress = isLoopbackAddress;
+exports.isLoopbackRequest = isLoopbackRequest;
+exports.extractBearerToken = extractBearerToken;
+exports.authContextFromRequest = authContextFromRequest;
+exports.timingSafeEqualStr = timingSafeEqualStr;
+exports.decideAccess = decideAccess;
+const crypto = __importStar(require("crypto"));
+/**
+ * remoteAddress 가 루프백인가. IPv4(127.0.0.0/8)·IPv6(::1)·IPv4-mapped(::ffff:127.x) 포함.
+ * 주의: 호스트명/헤더(X-Forwarded-For 등 *위조 가능*)는 신뢰하지 않는다 — 소켓 주소만.
+ */
+function isLoopbackAddress(addr) {
+    if (!addr)
+        return false;
+    let a = addr.trim().toLowerCase();
+    // IPv4-mapped IPv6 정규화: ::ffff:127.0.0.1 → 127.0.0.1
+    const mapped = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        a = mapped[1];
+    if (a === '::1')
+        return true;
+    // 127.0.0.0/8
+    const m = a.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (m) {
+        const o = m.slice(1).map(Number);
+        if (o.every((n) => n >= 0 && n <= 255) && o[0] === 127)
+            return true;
+    }
+    return false;
+}
+/** 요청 소켓이 루프백에서 왔는가(전송계층 판정). */
+function isLoopbackRequest(req) {
+    return isLoopbackAddress(req.socket?.remoteAddress);
+}
+/**
+ * 토큰 추출: Authorization: Bearer <t> → X-Dashboard-Token 헤더 → ?token= 쿼리.
+ * (EventSource/SSE 는 헤더를 못 실으므로 쿼리 폴백 허용.)
+ */
+function extractBearerToken(req) {
+    const auth = req.headers['authorization'];
+    if (typeof auth === 'string') {
+        const m = auth.match(/^Bearer\s+(.+)$/i);
+        if (m)
+            return m[1].trim();
+    }
+    const hdr = req.headers['x-dashboard-token'];
+    if (typeof hdr === 'string' && hdr.trim())
+        return hdr.trim();
+    // 쿼리 폴백(헤더 불가 클라이언트 전용).
+    const url = req.url || '';
+    const qi = url.indexOf('?');
+    if (qi >= 0) {
+        const qs = new URLSearchParams(url.slice(qi + 1));
+        const t = qs.get('token');
+        if (t)
+            return t;
+    }
+    return undefined;
+}
+/**
+ * H3 — 요청에서 AuthContext 를 *전송계층 기준*으로 구성한다.
+ * loopback 은 소켓 주소로 판정(클라이언트 제공 불리언/헤더 신뢰 금지), token 은 헤더/쿼리에서.
+ * 컴패니언/페어링은 반드시 이 함수로 컨텍스트를 만들어야 위조(loopback:true)를 막는다.
+ */
+function authContextFromRequest(req) {
+    return { token: extractBearerToken(req), loopback: isLoopbackRequest(req) };
+}
+/** 길이/내용 모두 timing-safe 비교(불일치 길이도 누설 안 함). */
+function timingSafeEqualStr(a, b) {
+    if (!a || !b)
+        return false;
+    const ha = crypto.createHash('sha256').update(a).digest();
+    const hb = crypto.createHash('sha256').update(b).digest();
+    return crypto.timingSafeEqual(ha, hb);
+}
+/**
+ * 표준 접근 정책(C1):
+ *   - 루프백 요청 → 허용(로컬 신뢰; 단 requireTokenAlways=true면 토큰도 요구).
+ *   - 비루프백 요청 → 유효 토큰 필수(없으면 거부).
+ * token 미설정(서버에 토큰 없음) + 비루프백 → 거부(안전 기본값).
+ */
+function decideAccess(req, serverToken, opts = {}) {
+    const loopback = isLoopbackRequest(req);
+    const presented = extractBearerToken(req);
+    const tokenOk = !!serverToken && timingSafeEqualStr(presented, serverToken);
+    if (opts.requireTokenAlways) {
+        return tokenOk
+            ? { ok: true, reason: 'ok', via: 'token' }
+            : { ok: false, reason: '토큰 필요', via: '' };
+    }
+    if (loopback)
+        return { ok: true, reason: 'ok(loopback)', via: 'loopback' };
+    if (tokenOk)
+        return { ok: true, reason: 'ok(token)', via: 'token' };
+    return { ok: false, reason: '비루프백 접근은 토큰 필요', via: '' };
+}