ipReputation.js

'use strict';

const ipaddr = require('ipaddr.js');
const { isPrivateOrLoopback, normalizeIpString } = require('./ip');
const { readBodyLimited } = require('./httpClient');

const PROXYCHECK_MAX_RESPONSE_BYTES = 64 * 1024;

const DEFAULTS = Object.freeze({
    timeoutMs: 2500,
    cacheTtlMs: 60 * 60 * 1000,
    cacheMaxEntries: 4096,
    maxInflight: 128,
    datacenterBlockRisk: 66,
    residentialReviewRisk: 90,
    sweeperIntervalMs: 5 * 60 * 1000,
});

// These are process-wide ceilings, even when a caller supplies unsafe settings.
const HARD_LIMITS = Object.freeze({
    timeoutMinMs: 100,
    timeoutMaxMs: 10000,
    cacheTtlMinMs: 1000,
    cacheTtlMaxMs: 24 * 60 * 60 * 1000,
    cacheMaxEntries: 50000,
    maxInflight: 1024,
    sweeperIntervalMinMs: 1000,
    sweeperIntervalMaxMs: 60 * 60 * 1000,
});

// Cache raw provider signals, not policy decisions. This lets an administrator
// change policy or thresholds without waiting for old verdicts to expire.
const cache = new Map(); // canonical IP -> { signal, createdAt, expires }
const inFlight = new Map(); // canonical IP -> Promise<signal>
const counters = new Map();

let sweeperTimer = null;
let sweeperClearInterval = clearInterval;
let sweeperMetrics = null;

function clampFinite(value, fallback, min, max) {
    const parsed = Number(value);
    const finite = Number.isFinite(parsed) ? parsed : fallback;
    return Math.min(max, Math.max(min, finite));
}

function clampInteger(value, fallback, min, max) {
    return Math.floor(clampFinite(value, fallback, min, max));
}

function boundedText(value, maxLength) {
    return String(value || '')
        .replace(/[\u0000-\u001f\u007f]/g, ' ')
        .trim()
        .slice(0, maxLength);
}

function incrementMetric(metrics, name, amount = 1) {
    counters.set(name, (counters.get(name) || 0) + amount);
    try { metrics?.increment?.(name, amount); } catch (error) { /* observability must fail open */ }
}

function setGauge(metrics, name, value) {
    try { metrics?.setGauge?.(name, value); } catch (error) { /* observability must fail open */ }
}

function updateSizeGauges(metrics) {
    setGauge(metrics, 'ip_reputation_cache_entries', cache.size);
    setGauge(metrics, 'ip_reputation_inflight', inFlight.size);
}

function normalizeConfig(cfg = {}) {
    const policy = ['log-only', 'datacenter', 'strict'].includes(cfg.policy)
        ? cfg.policy
        : 'log-only';
    return {
        enabled: cfg.enabled !== false,
        policy,
        apiKey: typeof cfg.apiKey === 'string' ? cfg.apiKey : '',
        timeoutMs: clampInteger(
            cfg.timeoutMs,
            DEFAULTS.timeoutMs,
            HARD_LIMITS.timeoutMinMs,
            HARD_LIMITS.timeoutMaxMs,
        ),
        cacheTtlMs: clampInteger(
            cfg.cacheTtlMs,
            DEFAULTS.cacheTtlMs,
            HARD_LIMITS.cacheTtlMinMs,
            HARD_LIMITS.cacheTtlMaxMs,
        ),
        cacheMaxEntries: clampInteger(
            cfg.cacheMaxEntries,
            DEFAULTS.cacheMaxEntries,
            1,
            HARD_LIMITS.cacheMaxEntries,
        ),
        maxInflight: clampInteger(
            cfg.maxInflight,
            DEFAULTS.maxInflight,
            1,
            HARD_LIMITS.maxInflight,
        ),
        datacenterBlockRisk: clampFinite(cfg.datacenterBlockRisk, DEFAULTS.datacenterBlockRisk, 0, 100),
        residentialReviewRisk: clampFinite(cfg.residentialReviewRisk, DEFAULTS.residentialReviewRisk, 0, 100),
        fetchFn: typeof cfg.fetchFn === 'function' ? cfg.fetchFn : globalThis.fetch,
        setTimeoutFn: typeof cfg.setTimeoutFn === 'function' ? cfg.setTimeoutFn : setTimeout,
        clearTimeoutFn: typeof cfg.clearTimeoutFn === 'function' ? cfg.clearTimeoutFn : clearTimeout,
        nowFn: typeof cfg.nowFn === 'function' ? cfg.nowFn : Date.now,
        metrics: cfg.metrics,
    };
}

const isMobile = type => ['wireless', 'mobile'].includes(String(type || '').toLowerCase());
const isDatacenter = type => ['hosting', 'datacenter', 'data center'].includes(String(type || '').toLowerCase());
const isVpnLike = type => ['vpn', 'tor', 'proxy'].includes(String(type || '').toLowerCase());

async function queryProxycheck(ip, config) {
    if (typeof config.fetchFn !== 'function') throw new Error('proxycheck fetch unavailable');
    const url = `https://proxycheck.io/v2/${encodeURIComponent(ip)}`
        + '?vpn=1&risk=1&asn=1'
        + (config.apiKey ? `&key=${encodeURIComponent(config.apiKey)}` : '');

    const controller = new AbortController();
    const requestPromise = (async () => {
        const response = await config.fetchFn(url, {
            signal: controller.signal,
            headers: { Accept: 'application/json' },
        });
        if (!response || !response.ok) {
            const status = Number.isFinite(Number(response?.status)) ? Number(response.status) : 'unknown';
            throw new Error(`proxycheck HTTP ${status}`);
        }
        const body = await readBodyLimited(response, PROXYCHECK_MAX_RESPONSE_BYTES);
        const data = JSON.parse(body.toString('utf8'));
        if (data?.status && data.status !== 'ok' && data.status !== 'warning') {
            throw new Error(`proxycheck status=${boundedText(data.status, 24)}`);
        }
        const record = data?.[ip];
        if (!record || typeof record !== 'object') throw new Error('proxycheck: no record for ip');
        return {
            proxy: record.proxy === true || String(record.proxy || '').toLowerCase() === 'yes',
            type: boundedText(record.type || 'Unknown', 40) || 'Unknown',
            risk: clampFinite(record.risk, 0, 0, 100),
            provider: boundedText(record.provider || record.organisation, 120),
            asn: boundedText(record.asn, 32),
            country: boundedText(record.country || record.isocode, 64),
        };
    })();
    // If the deadline wins, the injected/provider promise may ignore abort and
    // settle later. Attach a rejection handler so that losing work can never
    // become an unhandled rejection.
    requestPromise.catch(() => {});

    let timer;
    let settleTimeout;
    const timeoutPromise = new Promise((resolve, reject) => {
        settleTimeout = resolve;
        timer = config.setTimeoutFn(() => {
            controller.abort();
            reject(new Error('proxycheck timeout'));
        }, config.timeoutMs);
        timer?.unref?.();
    });
    try {
        return await Promise.race([requestPromise, timeoutPromise]);
    } finally {
        settleTimeout?.();
        if (timer !== undefined) {
            try { config.clearTimeoutFn(timer); } catch (error) { /* preserve fail-open semantics */ }
        }
    }
}

function classify(signal, config) {
    if (isMobile(signal.type) && !signal.proxy) {
        // Deliberate false-positive boundary: shared carrier/CGNAT addresses
        // remain Turnstile-gated, but an explicitly confirmed proxy signal
        // still proceeds to the policy layer (and strict mode blocks it).
        return { rawDecision: 'allow', rawFlagged: false, reason: `mobile-network(${signal.risk})` };
    }
    if (isDatacenter(signal.type)) {
        if (signal.risk >= config.datacenterBlockRisk || signal.proxy) {
            return { rawDecision: 'block', rawFlagged: true, reason: `datacenter-high-risk(risk=${signal.risk})` };
        }
        return { rawDecision: 'challenge', rawFlagged: true, reason: `datacenter-low-risk(risk=${signal.risk})` };
    }
    if (signal.proxy || isVpnLike(signal.type)) {
        return { rawDecision: 'challenge', rawFlagged: true, reason: `vpn/proxy(${signal.type})` };
    }
    if (signal.risk >= config.residentialReviewRisk) {
        return { rawDecision: 'challenge', rawFlagged: true, reason: `residential-very-high-risk(risk=${signal.risk})` };
    }
    return { rawDecision: 'allow', rawFlagged: signal.risk >= 66, reason: `${signal.type}(risk=${signal.risk})` };
}

function applyPolicy(raw, signal, policy) {
    if (policy === 'strict') {
        const decision = raw.rawDecision === 'allow' ? 'allow' : 'block';
        return { decision, flagged: decision !== 'allow', reason: raw.reason };
    }
    if (policy === 'datacenter') {
        if (raw.rawDecision === 'block' && isDatacenter(signal.type)) {
            return { decision: 'block', flagged: true, reason: raw.reason };
        }
        return {
            decision: 'allow',
            flagged: raw.rawFlagged || raw.rawDecision !== 'allow',
            reason: raw.reason,
        };
    }
    return {
        decision: 'allow',
        flagged: raw.rawFlagged || raw.rawDecision !== 'allow',
        reason: raw.reason,
    };
}

function baseVerdict(reason, source) {
    return {
        decision: 'allow',
        flagged: false,
        reason,
        type: 'Unknown',
        risk: 0,
        provider: '',
        asn: '',
        country: '',
        proxy: false,
        source,
    };
}

function verdictFromSignal(signal, config, source) {
    const raw = classify(signal, config);
    const policied = applyPolicy(raw, signal, config.policy);
    return {
        decision: policied.decision,
        flagged: policied.flagged,
        reason: policied.reason,
        type: signal.type,
        risk: signal.risk,
        provider: signal.provider,
        asn: signal.asn,
        country: signal.country,
        proxy: signal.proxy,
        source,
    };
}

function evictOldest(metrics) {
    const oldestKey = cache.keys().next().value;
    if (oldestKey === undefined) return false;
    cache.delete(oldestKey);
    incrementMetric(metrics, 'ip_reputation_cache_eviction');
    return true;
}

function trimCache(maxEntries, metrics) {
    while (cache.size > maxEntries) evictOldest(metrics);
    updateSizeGauges(metrics);
}

function getCachedSignal(ip, config, now) {
    const entry = cache.get(ip);
    if (!entry) return null;
    // A caller may lower the TTL after this entry was created. Honour the
    // current setting as well as the creator's expiry.
    const effectiveExpiry = Math.min(entry.expires, entry.createdAt + config.cacheTtlMs);
    if (effectiveExpiry <= now) {
        cache.delete(ip);
        incrementMetric(config.metrics, 'ip_reputation_cache_expired');
        updateSizeGauges(config.metrics);
        return null;
    }
    // Map insertion order doubles as a bounded LRU approximation.
    cache.delete(ip);
    cache.set(ip, entry);
    incrementMetric(config.metrics, 'ip_reputation_cache_hit');
    return entry.signal;
}

function storeSignal(ip, signal, config) {
    if (cache.has(ip)) cache.delete(ip);
    while (cache.size >= config.cacheMaxEntries) evictOldest(config.metrics);
    const createdAt = config.nowFn();
    cache.set(ip, {
        signal,
        createdAt,
        expires: createdAt + config.cacheTtlMs,
    });
    updateSizeGauges(config.metrics);
}

function canonicalIp(ip) {
    if (typeof ip !== 'string') return null;
    const candidate = ip.trim();
    if (!candidate || !ipaddr.isValid(candidate)) return null;
    return normalizeIpString(candidate);
}

async function evaluateIp(ip, cfg = {}) {
    const config = normalizeConfig(cfg);
    const normalizedIp = canonicalIp(ip);
    if (!normalizedIp) return baseVerdict(ip ? 'invalid-ip' : 'no-ip', 'invalid');
    if (isPrivateOrLoopback(normalizedIp)) {
        return {
            ...baseVerdict('local-network', 'local'),
            type: 'Local',
            country: 'Local',
        };
    }
    if (!config.enabled) return baseVerdict('ip-check-disabled', 'disabled');

    trimCache(config.cacheMaxEntries, config.metrics);
    const cachedSignal = getCachedSignal(normalizedIp, config, config.nowFn());
    if (cachedSignal) return verdictFromSignal(cachedSignal, config, 'cache');
    incrementMetric(config.metrics, 'ip_reputation_cache_miss');

    let pending = inFlight.get(normalizedIp);
    let source = 'coalesced';
    if (pending) {
        incrementMetric(config.metrics, 'ip_reputation_inflight_join');
    } else {
        if (inFlight.size >= config.maxInflight || inFlight.size >= HARD_LIMITS.maxInflight) {
            incrementMetric(config.metrics, 'ip_reputation_capacity_failopen');
            updateSizeGauges(config.metrics);
            return baseVerdict('ipcheck-capacity', 'capacity');
        }
        source = 'proxycheck';
        incrementMetric(config.metrics, 'ip_reputation_upstream_request');
        pending = queryProxycheck(normalizedIp, config)
            .then(signal => {
                storeSignal(normalizedIp, signal, config);
                return signal;
            })
            .finally(() => {
                if (inFlight.get(normalizedIp) === pending) inFlight.delete(normalizedIp);
                updateSizeGauges(config.metrics);
            });
        inFlight.set(normalizedIp, pending);
        updateSizeGauges(config.metrics);
    }

    try {
        const signal = await pending;
        return verdictFromSignal(signal, config, source);
    } catch (error) {
        incrementMetric(config.metrics, 'ip_reputation_failopen');
        const detail = boundedText(error?.message || 'upstream-failure', 160);
        return baseVerdict(`ipcheck-failopen: ${detail}`, 'failopen');
    }
}

function clearCache(metrics) {
    cache.clear();
    updateSizeGauges(metrics);
}

function sweepCache(options = {}) {
    const opts = typeof options === 'number' ? { now: options } : (options || {});
    const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
    let removed = 0;
    for (const [key, entry] of cache) {
        if (entry.expires <= now) {
            cache.delete(key);
            removed += 1;
        }
    }
    if (removed) incrementMetric(opts.metrics, 'ip_reputation_cache_swept', removed);
    updateSizeGauges(opts.metrics);
    return removed;
}

function stopCacheSweeper() {
    if (sweeperTimer === null) return false;
    sweeperClearInterval(sweeperTimer);
    sweeperTimer = null;
    setGauge(sweeperMetrics, 'ip_reputation_sweeper_running', 0);
    sweeperMetrics = null;
    sweeperClearInterval = clearInterval;
    return true;
}

function startCacheSweeper(value = {}) {
    const opts = typeof value === 'number' ? { intervalMs: value } : (value || {});
    stopCacheSweeper();
    const intervalMs = clampInteger(
        opts.intervalMs,
        DEFAULTS.sweeperIntervalMs,
        HARD_LIMITS.sweeperIntervalMinMs,
        HARD_LIMITS.sweeperIntervalMaxMs,
    );
    const setIntervalFn = typeof opts.setIntervalFn === 'function' ? opts.setIntervalFn : setInterval;
    sweeperClearInterval = typeof opts.clearIntervalFn === 'function' ? opts.clearIntervalFn : clearInterval;
    sweeperMetrics = opts.metrics;
    sweeperTimer = setIntervalFn(() => sweepCache({ metrics: opts.metrics }), intervalMs);
    sweeperTimer?.unref?.();
    updateSizeGauges(opts.metrics);
    setGauge(opts.metrics, 'ip_reputation_sweeper_running', 1);
    return sweeperTimer;
}

function getReputationMetrics() {
    return {
        cacheSize: cache.size,
        inFlightSize: inFlight.size,
        sweeperRunning: sweeperTimer !== null,
        counters: Object.fromEntries(counters),
    };
}

module.exports = {
    evaluateIp,
    clearCache,
    sweepCache,
    startCacheSweeper,
    stopCacheSweeper,
    getReputationMetrics,
    normalizeConfig,
    DEFAULTS,
    HARD_LIMITS,
};