@jshookmcp/jshook 0.1.7 → 0.1.9

package/dist/src/server/domains/maintenance/handlers.extensions.js

@@ -0,0 +1,436 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { logger } from '../../../utils/logger.js';
+import { EXTENSION_GIT_CLONE_TIMEOUT_MS, EXTENSION_GIT_CHECKOUT_TIMEOUT_MS, } from '../../../constants.js';
+import { asJsonResponse, serializeError } from '../../domains/shared/response.js';
+const execFileAsync = promisify(execFile);
+function getJshookInstallRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    return resolve(dirname(currentFile), '..', '..', '..', '..');
+}
+function parseFirstRoot(raw) {
+    const value = raw?.trim();
+    if (!value)
+        return undefined;
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .find((item) => item.length > 0);
+}
+function resolveDefaultExtensionRoot(kind) {
+    const envKey = kind === 'workflow' ? 'MCP_WORKFLOW_ROOTS' : 'MCP_PLUGIN_ROOTS';
+    const configured = parseFirstRoot(process.env[envKey]);
+    if (configured) {
+        return resolve(configured);
+    }
+    const installRoot = getJshookInstallRoot();
+    return resolve(installRoot, kind === 'workflow' ? 'workflows' : 'plugins');
+}
+function getRegistryBaseUrl() {
+    const baseUrl = (process.env.EXTENSION_REGISTRY_BASE_URL ?? '').trim().replace(/\/+$/, '');
+    if (!baseUrl) {
+        throw new Error('EXTENSION_REGISTRY_BASE_URL is not configured. Set it in .env or environment before browsing or installing extensions.');
+    }
+    return baseUrl;
+}
+const LOCAL_EXTENSION_SDK_PACKAGE = '@jshookmcp/extension-sdk';
+const LOCAL_EXTENSION_SDK_ROOT = resolve(getJshookInstallRoot(), 'packages', 'extension-sdk');
+const REGISTRY_FETCH_TIMEOUT_MS = 10_000;
+const REGISTRY_CACHE_DIR = resolve(homedir(), '.jshookmcp', 'cache');
+class RegistryFetchError extends Error {
+    code;
+    url;
+    cachePath;
+    status;
+    constructor(code, url, message, cachePath, status) {
+        super(message);
+        this.code = code;
+        this.url = url;
+        this.cachePath = cachePath;
+        this.status = status;
+        this.name = 'RegistryFetchError';
+    }
+}
+function resolvePackageManagerInvocation(packageManager, args) {
+    if (process.platform === 'win32') {
+        return {
+            command: 'powershell.exe',
+            args: ['-NoProfile', '-NonInteractive', '-Command', `${packageManager} ${args.join(' ')}`],
+        };
+    }
+    return { command: packageManager, args };
+}
+async function execPackageManager(packageManager, args, options) {
+    const invocation = resolvePackageManagerInvocation(packageManager, args);
+    return execFileAsync(invocation.command, invocation.args, {
+        ...options,
+        env: {
+            ...process.env,
+            ...options?.env,
+            CI: 'true',
+        },
+    });
+}
+async function resolvePackageManager(installDir) {
+    const packageJsonPath = resolve(installDir, 'package.json');
+    const pnpmLockPath = resolve(installDir, 'pnpm-lock.yaml');
+    const npmLockPath = resolve(installDir, 'package-lock.json');
+    if (existsSync(packageJsonPath)) {
+        try {
+            const raw = await readFile(packageJsonPath, 'utf8');
+            const pkg = JSON.parse(raw);
+            const packageManager = pkg.packageManager?.trim().toLowerCase().split('@')[0];
+            if (packageManager === 'pnpm')
+                return 'pnpm';
+            if (packageManager === 'npm')
+                return 'npm';
+        }
+        catch {
+        }
+    }
+    if (existsSync(pnpmLockPath))
+        return 'pnpm';
+    if (existsSync(npmLockPath))
+        return 'npm';
+    return 'pnpm';
+}
+function getRegistryCachePath(kind) {
+    return resolve(REGISTRY_CACHE_DIR, `registry-${kind}.json`);
+}
+async function readRegistryCache(kind) {
+    const cachePath = getRegistryCachePath(kind);
+    try {
+        const raw = await readFile(cachePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeRegistryCache(kind, payload) {
+    const cachePath = getRegistryCachePath(kind);
+    await mkdir(dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, JSON.stringify(payload, null, 2), 'utf8');
+}
+function classifyRegistryFetchError(url, error, cachePath) {
+    if (error instanceof RegistryFetchError) {
+        return error;
+    }
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return new RegistryFetchError('timeout', url, `Registry fetch timed out after ${REGISTRY_FETCH_TIMEOUT_MS}ms: ${url}`, cachePath);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('ENOTFOUND') || message.includes('getaddrinfo')) {
+        return new RegistryFetchError('dns_failure', url, `DNS resolution failed for registry URL: ${url}`, cachePath);
+    }
+    if (message.includes('ECONNREFUSED')) {
+        return new RegistryFetchError('connection_refused', url, `Connection refused by registry server: ${url}`, cachePath);
+    }
+    if (message.includes('CERT_') || message.includes('certificate') || message.includes('SSL')) {
+        return new RegistryFetchError('tls_error', url, `TLS/certificate error when connecting to registry: ${url}`, cachePath);
+    }
+    const httpMatch = message.match(/HTTP\s+(\d+)/i);
+    if (httpMatch) {
+        const status = Number(httpMatch[1]);
+        return new RegistryFetchError('http_error', url, message, cachePath, status);
+    }
+    return new RegistryFetchError('fetch_failed', url, message, cachePath);
+}
+function serializeRegistryFetchError(error) {
+    return {
+        success: false,
+        error: error.code,
+        message: error.message,
+        url: error.url,
+        ...(typeof error.status === 'number' ? { status: error.status } : {}),
+        ...(error.cachePath ? { cachePath: error.cachePath } : {}),
+    };
+}
+async function fetchJson(url, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REGISTRY_FETCH_TIMEOUT_MS);
+    const cachePath = options?.cacheKey ? getRegistryCachePath(options.cacheKey) : undefined;
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok) {
+            throw new RegistryFetchError('http_error', url, `HTTP ${res.status} ${res.statusText} from ${url}`, cachePath, res.status);
+        }
+        const data = await res.json();
+        if (options?.cacheKey) {
+            try {
+                await writeRegistryCache(options.cacheKey, data);
+            }
+            catch (cacheError) {
+                logger.warn(`[extensions] Failed to persist ${options.cacheKey} registry cache for ${url}:`, cacheError);
+            }
+        }
+        return {
+            data,
+            stale: false,
+            source: 'network',
+            cachePath,
+        };
+    }
+    catch (error) {
+        const classified = classifyRegistryFetchError(url, error, cachePath);
+        if (options?.cacheKey) {
+            const cached = await readRegistryCache(options.cacheKey);
+            if (cached) {
+                logger.warn(`[extensions] Using stale ${options.cacheKey} registry cache after ${classified.code}: ${url}`);
+                return {
+                    data: cached,
+                    stale: true,
+                    source: 'cache',
+                    cachePath,
+                };
+            }
+        }
+        throw classified;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function rewriteLocalExtensionSdkDependency(installDir) {
+    const packageJsonPath = resolve(installDir, 'package.json');
+    if (!existsSync(packageJsonPath)) {
+        return false;
+    }
+    try {
+        const raw = await readFile(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(raw);
+        const sections = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+        const relativeSdkPath = relative(installDir, LOCAL_EXTENSION_SDK_ROOT).replace(/\\/g, '/');
+        const localSdkSpec = `file:${relativeSdkPath || '.'}`;
+        let changed = false;
+        for (const sectionName of sections) {
+            const section = pkg[sectionName];
+            if (!section || typeof section !== 'object') {
+                continue;
+            }
+            const dependencyMap = section;
+            const currentValue = dependencyMap[LOCAL_EXTENSION_SDK_PACKAGE];
+            if (typeof currentValue === 'string' && currentValue.startsWith('workspace:')) {
+                dependencyMap[LOCAL_EXTENSION_SDK_PACKAGE] = localSdkSpec;
+                changed = true;
+            }
+        }
+        if (!changed) {
+            return false;
+        }
+        await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+        logger.info(`[extensions] Rewrote ${LOCAL_EXTENSION_SDK_PACKAGE} dependency to local file path for ${installDir}`);
+        return true;
+    }
+    catch (error) {
+        logger.warn(`[extensions] Failed to rewrite ${LOCAL_EXTENSION_SDK_PACKAGE} dependency for ${installDir}:`, error);
+        return false;
+    }
+}
+async function findRegistryEntryBySlug(registryBase, slug) {
+    const [workflowResult, pluginResult] = await Promise.allSettled([
+        fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: 'workflows' }),
+        fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: 'plugins' }),
+    ]);
+    if (workflowResult.status === 'fulfilled') {
+        const workflows = Array.isArray(workflowResult.value.data.workflows)
+            ? workflowResult.value.data.workflows
+            : [];
+        const workflowEntry = workflows.find((item) => item.slug === slug);
+        if (workflowEntry) {
+            return { entry: workflowEntry, kind: 'workflow' };
+        }
+    }
+    if (pluginResult.status === 'fulfilled') {
+        const plugins = Array.isArray(pluginResult.value.data.plugins)
+            ? pluginResult.value.data.plugins
+            : [];
+        const pluginEntry = plugins.find((item) => item.slug === slug);
+        if (pluginEntry) {
+            return { entry: pluginEntry, kind: 'plugin' };
+        }
+    }
+    const workflowFetchError = workflowResult.status === 'rejected'
+        ? workflowResult.reason instanceof Error
+            ? workflowResult.reason
+            : new Error(String(workflowResult.reason))
+        : undefined;
+    const pluginFetchError = pluginResult.status === 'rejected'
+        ? pluginResult.reason instanceof Error
+            ? pluginResult.reason
+            : new Error(String(pluginResult.reason))
+        : undefined;
+    if (workflowFetchError && pluginFetchError) {
+        throw new Error(`Failed to resolve extension slug "${slug}": workflow registry error: ${workflowFetchError.message}; plugin registry error: ${pluginFetchError.message}`);
+    }
+    if (pluginFetchError) {
+        throw new Error(`Extension "${slug}" was not found in workflow registry, and plugin registry lookup failed: ${pluginFetchError.message}`);
+    }
+    if (workflowFetchError) {
+        throw new Error(`Extension "${slug}" was not found in plugin registry, and workflow registry lookup failed: ${workflowFetchError.message}`);
+    }
+    throw new Error(`Extension "${slug}" not found in workflow or plugin registry`);
+}
+export class ExtensionManagementHandlers {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async handleListExtensions() {
+        try {
+            const result = this.ctx.listExtensions();
+            return asJsonResponse({ success: true, ...result });
+        }
+        catch (error) {
+            logger.error('Failed to list extensions:', error);
+            return asJsonResponse(serializeError(error));
+        }
+    }
+    async handleReloadExtensions() {
+        try {
+            const result = await this.ctx.reloadExtensions();
+            return asJsonResponse({ success: true, ...result });
+        }
+        catch (error) {
+            logger.error('Failed to reload extensions:', error);
+            return asJsonResponse(serializeError(error));
+        }
+    }
+    async handleBrowseExtensionRegistry(kind) {
+        try {
+            const registryBase = getRegistryBaseUrl();
+            const showPlugins = kind === 'all' || kind === 'plugin';
+            const showWorkflows = kind === 'all' || kind === 'workflow';
+            const result = { success: true };
+            let stale = false;
+            const pluginPromise = showPlugins
+                ? fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: 'plugins' })
+                : undefined;
+            const workflowPromise = showWorkflows
+                ? fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: 'workflows' })
+                : undefined;
+            const [pluginIndex, workflowIndex] = await Promise.all([
+                pluginPromise ?? Promise.resolve(undefined),
+                workflowPromise ?? Promise.resolve(undefined),
+            ]);
+            if (pluginIndex) {
+                const plugins = Array.isArray(pluginIndex.data.plugins) ? pluginIndex.data.plugins : [];
+                result.plugins = plugins.map((p) => ({
+                    slug: p.slug,
+                    id: p.id,
+                    name: p.meta.name,
+                    description: p.meta.description,
+                    author: p.meta.author,
+                    repo: p.source.repo,
+                    commit: p.source.commit,
+                    entry: p.source.entry,
+                }));
+                result.pluginCount = plugins.length;
+                result.pluginSource = pluginIndex.source;
+                stale = stale || pluginIndex.stale;
+            }
+            if (workflowIndex) {
+                const workflows = Array.isArray(workflowIndex.data.workflows) ? workflowIndex.data.workflows : [];
+                result.workflows = workflows.map((w) => ({
+                    slug: w.slug,
+                    id: w.id,
+                    name: w.meta.name,
+                    description: w.meta.description,
+                    author: w.meta.author,
+                    repo: w.source.repo,
+                    commit: w.source.commit,
+                    entry: w.source.entry,
+                }));
+                result.workflowCount = workflows.length;
+                result.workflowSource = workflowIndex.source;
+                stale = stale || workflowIndex.stale;
+            }
+            if (stale) {
+                result.stale = true;
+            }
+            return asJsonResponse(result);
+        }
+        catch (error) {
+            logger.error('Failed to browse extension registry:', error);
+            if (error instanceof RegistryFetchError) {
+                return asJsonResponse(serializeRegistryFetchError(error));
+            }
+            return asJsonResponse(serializeError(error));
+        }
+    }
+    async handleInstallExtension(slug, targetDir) {
+        try {
+            const registryBase = getRegistryBaseUrl();
+            const { entry, kind } = await findRegistryEntryBySlug(registryBase, slug);
+            const isWorkflow = kind === 'workflow';
+            const defaultRoot = resolveDefaultExtensionRoot(isWorkflow ? 'workflow' : 'plugin');
+            const installDir = targetDir
+                ? resolve(targetDir)
+                : resolve(defaultRoot, slug);
+            if (existsSync(installDir)) {
+                return asJsonResponse({
+                    success: false,
+                    error: `Target directory already exists: ${installDir}`,
+                    hint: 'Remove the existing directory first, or specify a different targetDir',
+                });
+            }
+            await mkdir(dirname(installDir), { recursive: true });
+            await execFileAsync('git', ['clone', entry.source.repo, installDir], {
+                timeout: EXTENSION_GIT_CLONE_TIMEOUT_MS,
+            });
+            await execFileAsync('git', ['-C', installDir, 'checkout', entry.source.commit], {
+                timeout: EXTENSION_GIT_CHECKOUT_TIMEOUT_MS,
+            });
+            const packageJsonPath = resolve(installDir, 'package.json');
+            if (existsSync(packageJsonPath)) {
+                await rewriteLocalExtensionSdkDependency(installDir);
+                const packageManager = await resolvePackageManager(installDir);
+                const installArgs = packageManager === 'pnpm'
+                    ? ['--ignore-workspace', 'install', '--no-frozen-lockfile']
+                    : ['install'];
+                await execPackageManager(packageManager, installArgs, {
+                    cwd: installDir,
+                    timeout: Math.max(EXTENSION_GIT_CLONE_TIMEOUT_MS, 120_000),
+                });
+                const buildArgs = packageManager === 'pnpm'
+                    ? ['--ignore-workspace', 'run', '--if-present', 'build']
+                    : ['run', 'build', '--if-present'];
+                await execPackageManager(packageManager, buildArgs, {
+                    cwd: installDir,
+                    timeout: Math.max(EXTENSION_GIT_CLONE_TIMEOUT_MS, 120_000),
+                });
+            }
+            const reloadResult = await this.ctx.reloadExtensions();
+            return asJsonResponse({
+                success: true,
+                installed: {
+                    slug: entry.slug,
+                    id: entry.id,
+                    name: entry.meta.name,
+                    repo: entry.source.repo,
+                    commit: entry.source.commit,
+                    installDir,
+                },
+                reload: {
+                    addedTools: reloadResult.addedTools,
+                    pluginCount: reloadResult.pluginCount,
+                    workflowCount: reloadResult.workflowCount,
+                    errors: reloadResult.errors,
+                    warnings: reloadResult.warnings,
+                },
+            });
+        }
+        catch (error) {
+            logger.error('Failed to install extension:', error);
+            if (error instanceof RegistryFetchError) {
+                return asJsonResponse(serializeRegistryFetchError(error));
+            }
+            return asJsonResponse(serializeError(error));
+        }
+    }
+}

package/dist/src/server/domains/maintenance/manifest.js

@@ -0,0 +1,44 @@
+import { bindByDepKey, toolLookup } from '../../domains/shared/registry.js';
+import { tokenBudgetTools, cacheTools, extensionTools, artifactTools } from '../../domains/maintenance/definitions.js';
+import { CoreMaintenanceHandlers, ExtensionManagementHandlers } from '../../domains/maintenance/index.js';
+const DOMAIN = 'maintenance';
+const DEP_KEY = 'coreMaintenanceHandlers';
+const EXT_DEP_KEY = 'extensionManagementHandlers';
+const t = toolLookup([...tokenBudgetTools, ...cacheTools, ...artifactTools, ...extensionTools]);
+const b = (invoke) => bindByDepKey(DEP_KEY, invoke);
+const be = (invoke) => bindByDepKey(EXT_DEP_KEY, invoke);
+function ensure(ctx) {
+    if (!ctx.coreMaintenanceHandlers) {
+        ctx.coreMaintenanceHandlers = new CoreMaintenanceHandlers({
+            tokenBudget: ctx.tokenBudget,
+            unifiedCache: ctx.unifiedCache,
+        });
+    }
+    if (!ctx.extensionManagementHandlers) {
+        ctx.extensionManagementHandlers = new ExtensionManagementHandlers(ctx);
+    }
+    return ctx.coreMaintenanceHandlers;
+}
+const manifest = {
+    kind: 'domain-manifest',
+    version: 1,
+    domain: DOMAIN,
+    depKey: DEP_KEY,
+    profiles: ['search', 'workflow', 'full'],
+    ensure,
+    registrations: [
+        { tool: t('get_token_budget_stats'), domain: DOMAIN, bind: b((h) => h.handleGetTokenBudgetStats()) },
+        { tool: t('manual_token_cleanup'), domain: DOMAIN, bind: b((h) => h.handleManualTokenCleanup()) },
+        { tool: t('reset_token_budget'), domain: DOMAIN, bind: b((h) => h.handleResetTokenBudget()) },
+        { tool: t('get_cache_stats'), domain: DOMAIN, bind: b((h) => h.handleGetCacheStats()) },
+        { tool: t('smart_cache_cleanup'), domain: DOMAIN, bind: b((h, a) => h.handleSmartCacheCleanup(a.targetSize)) },
+        { tool: t('clear_all_caches'), domain: DOMAIN, bind: b((h) => h.handleClearAllCaches()) },
+        { tool: t('cleanup_artifacts'), domain: DOMAIN, bind: b((h, a) => h.handleCleanupArtifacts({ retentionDays: a.retentionDays, maxTotalBytes: a.maxTotalBytes, dryRun: a.dryRun })) },
+        { tool: t('doctor_environment'), domain: DOMAIN, bind: b((h, a) => h.handleEnvironmentDoctor({ includeBridgeHealth: a.includeBridgeHealth })) },
+        { tool: t('list_extensions'), domain: DOMAIN, bind: be((h) => h.handleListExtensions()) },
+        { tool: t('reload_extensions'), domain: DOMAIN, bind: be((h) => h.handleReloadExtensions()) },
+        { tool: t('browse_extension_registry'), domain: DOMAIN, bind: be((h, a) => h.handleBrowseExtensionRegistry(a.kind ?? 'all')) },
+        { tool: t('install_extension'), domain: DOMAIN, bind: be((h, a) => h.handleInstallExtension(a.slug, a.targetDir)) },
+    ],
+};
+export default manifest;

package/dist/src/server/domains/network/replay.js

@@ -0,0 +1,179 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const STRIPPED_HEADERS = new Set([
+    'host',
+    'content-length',
+    'transfer-encoding',
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailers',
+    'upgrade',
+]);
+const SSRF_DENYLIST = [
+    /^127\./,
+    /^10\./,
+    /^172\.(1[6-9]|2[0-9]|3[01])\./,
+    /^192\.168\./,
+    /^169\.254\./,
+    /^0\./,
+    /^::1$/,
+    /^::$/,
+    /^::ffff:/i,
+    /^::ffff:0:/i,
+    /^64:ff9b::/i,
+    /^fc00:/i,
+    /^fd/i,
+    /^fe80:/i,
+    /^100::/i,
+    /^localhost$/i,
+];
+const LOOPBACK_HTTP_URL_RE = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(\/|$)/i;
+export function isPrivateHost(host) {
+    if (host.startsWith('[') && host.endsWith(']')) {
+        host = host.slice(1, -1);
+    }
+    return SSRF_DENYLIST.some((re) => re.test(host));
+}
+export function isLoopbackHost(host) {
+    const normalized = host.replace(/^\[|\]$/g, '').toLowerCase();
+    return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1';
+}
+export async function isSsrfTarget(url) {
+    try {
+        const parsed = new URL(url);
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+        if (isPrivateHost(hostname))
+            return true;
+        try {
+            const { address } = await lookup(hostname);
+            if (isPrivateHost(address))
+                return true;
+        }
+        catch {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function sanitizeHeaders(headers) {
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(headers)) {
+        if (!STRIPPED_HEADERS.has(k.toLowerCase()) && !DANGEROUS_KEYS.has(k)) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+export async function replayRequest(base, args, maxBodyBytes = 512_000) {
+    const url = args.urlOverride ?? base.url;
+    const method = (args.methodOverride ?? base.method).toUpperCase();
+    const mergedHeaders = sanitizeHeaders({ ...base.headers, ...args.headerPatch });
+    const body = args.bodyPatch !== undefined ? args.bodyPatch : base.postData;
+    const resolvePinned = async (targetUrl) => {
+        const parsed = new URL(targetUrl);
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+        if (parsed.protocol === 'http:' && !isLoopbackHost(hostname)) {
+            throw new Error(`Replay blocked: insecure HTTP is only allowed for loopback targets, got "${targetUrl}"`);
+        }
+        if (isPrivateHost(hostname)) {
+            throw new Error(`Replay blocked: target URL "${targetUrl}" resolves to a private/reserved address.`);
+        }
+        const isIpLiteral = isIP(hostname) !== 0;
+        if (isIpLiteral) {
+            return { pinnedUrl: targetUrl, originalHost: parsed.host };
+        }
+        let resolvedIp;
+        try {
+            const result = await lookup(hostname);
+            resolvedIp = result.address;
+        }
+        catch {
+            throw new Error(`Replay blocked: DNS resolution failed for "${targetUrl}"`);
+        }
+        if (isPrivateHost(resolvedIp)) {
+            throw new Error(`Replay blocked: "${targetUrl}" resolved to private IP ${resolvedIp}`);
+        }
+        if (parsed.protocol === 'https:') {
+            return { pinnedUrl: targetUrl, originalHost: parsed.host };
+        }
+        const originalHost = parsed.host;
+        parsed.hostname = resolvedIp.includes(':') ? `[${resolvedIp}]` : resolvedIp;
+        return { pinnedUrl: parsed.toString(), originalHost };
+    };
+    if (args.dryRun !== false) {
+        if (await isSsrfTarget(url)) {
+            throw new Error(`Replay blocked: target URL "${url}" resolves to a private/reserved address.`);
+        }
+        return {
+            dryRun: true,
+            preview: { url, method, headers: mergedHeaders, body },
+        };
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), args.timeoutMs ?? 30_000);
+    const MAX_REDIRECTS = 5;
+    try {
+        let currentUrl = url;
+        let currentMethod = method;
+        let currentBody = body;
+        let resp;
+        for (let hop = 0; hop < MAX_REDIRECTS; hop++) {
+            const { pinnedUrl, originalHost } = await resolvePinned(currentUrl);
+            if (!pinnedUrl.startsWith('https://') && !LOOPBACK_HTTP_URL_RE.test(pinnedUrl)) {
+                throw new Error(`Replay blocked: insecure HTTP is only allowed for loopback targets, got "${currentUrl}"`);
+            }
+            const hopHeaders = { ...mergedHeaders };
+            if (pinnedUrl !== currentUrl && !hopHeaders['host'] && !hopHeaders['Host']) {
+                hopHeaders['Host'] = originalHost;
+            }
+            resp = await fetch(pinnedUrl, {
+                method: currentMethod,
+                headers: hopHeaders,
+                body: currentMethod !== 'GET' && currentMethod !== 'HEAD' ? currentBody : undefined,
+                signal: controller.signal,
+                redirect: 'manual',
+            });
+            if (resp.status >= 300 && resp.status < 400) {
+                const location = resp.headers.get('location');
+                if (!location)
+                    break;
+                currentUrl = new URL(location, currentUrl).toString();
+                if (resp.status === 301 || resp.status === 302 || resp.status === 303) {
+                    currentMethod = 'GET';
+                    currentBody = undefined;
+                }
+                delete mergedHeaders['Host'];
+                delete mergedHeaders['host'];
+                continue;
+            }
+            break;
+        }
+        if (resp.status >= 300 && resp.status < 400) {
+            throw new Error(`Replay blocked: too many redirects (>${MAX_REDIRECTS})`);
+        }
+        const responseHeaders = {};
+        resp.headers.forEach((v, k) => { responseHeaders[k] = v; });
+        const rawText = await resp.text();
+        const bodyTruncated = rawText.length > maxBodyBytes;
+        const bodyOut = bodyTruncated ? rawText.slice(0, maxBodyBytes) : rawText;
+        return {
+            dryRun: false,
+            status: resp.status,
+            statusText: resp.statusText,
+            headers: responseHeaders,
+            body: bodyOut,
+            bodyTruncated,
+            requestId: args.requestId,
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}