deel-local-cli 1.5.8 → 1.6.0

package/src/backend/http.js

@@ -2,7 +2,24 @@
 //
 // 이 파일이 프로그램에서 바깥으로 나가는 유일한 문이다.
 // 나가기 전에 반드시 safety/network.js 의 문지기에게 물어본다.
+//
+// 길은 둘이고, 둘 다 이 파일 안에만 있다:
+//   · 직접 — Node 의 fetch.
+//   · 프록시 경유 — HTTPS_PROXY 같은 것이 있을 때(backend/proxy.js 가 고른다).
+//     Node 의 fetch 는 그 변수를 **안 본다.** 그래서 여기서 터널을 직접 뚫는다 —
+//     node:http 로 프록시에 CONNECT 를 보내고, 열린 소켓 위에 node:tls 를 올리고,
+//     그 위로 node:https 요청을 보낸다. http 대상은 프록시에 절대 주소로 그냥 보낸다.
+//     소켓을 만지는 코드가 이 파일 밖에 생기면 test/network.test.js 가 잡는다.
+//
+// 되돌림(redirect)은 어느 길이든 **한 홉마다** 문지기를 다시 지난다. fetch 의
+// redirect:'follow' 는 옮겨 간 자리를 안 물어봐서, 서버가 다른 집으로 되돌리면
+// 요청이 그리로 갔다. 이제는 그 홉에서 막히고, 다른 집으로 갈 때는 열쇠 머리말을 뗀다.
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { connect as tlsConnect } from 'node:tls';
+import { Readable } from 'node:stream';
 import { checkUrl, NetBlocked } from '../safety/network.js';
+import { 프록시고르기 } from './proxy.js';
 
 export const AUTH_STYLES = [
   { id: 'bearer', label: 'Authorization: Bearer', apply: (h, k) => { h['Authorization'] = `Bearer ${k}`; } },
@@ -25,6 +42,7 @@ export const AUTH_STYLES = [
  *
  * 그래서 잘라 내는 대신 닫는다. 이 자리는 Node 내부 이름이라 없을 수도 있으므로,
  * 없으면 조용히 넘어간다 — 그때는 부르는 쪽의 시간제한이 받아 준다.
+ * 프록시 길은 요청마다 소켓을 새로 열고 끝나면 닫으므로(Connection: close) 여기 안 온다.
  */
 export function closeConnections() {
   try {
@@ -37,56 +55,358 @@ export function closeConnections() {
 export function headersFor(authStyle, key, extra = {}) {
   const h = { 'Content-Type': 'application/json', Accept: 'application/json', ...extra };
   const style = AUTH_STYLES.find((s) => s.id === authStyle) ?? AUTH_STYLES[0];
-  if (key) style.apply(h, key);
+  // 앞뒤 공백·줄바꿈은 떼고 싣는다. 열쇠를 파일이나 메일에서 복사해 오면
+  // 줄바꿈이 딸려 오는 일이 흔한데, 그것 하나로 요청이 아예 안 만들어진다.
+  // 가운데 낀 것은 안 건드린다 — 그건 진짜 잘못된 열쇠이고, 조용히 고쳐 주면
+  // 무엇이 틀렸는지 영영 모른다.
+  const k = typeof key === 'string' ? key.trim() : key;
+  if (k) style.apply(h, k);
   return h;
 }
 
+// 사용자가 Ctrl+C 로 끊었다는 뜻. 통신 오류와 구분하려고 따로 둔다.
+export class Aborted extends Error {
+  constructor() { super('사용자가 중단했습니다'); this.name = 'Aborted'; }
+}
+
+/**
+ * JSON 을 주고받는 요청. 오류는 던지지 않고 { ok:false, error } 로 돌려준다 —
+ * 부르는 쪽이 사람 말로 된 한 줄을 그대로 보여 주면 되게.
+ * 자물쇠(NetBlocked)와 사용자 중단(Aborted)만 던진다. 둘은 통신 실패가 아니다.
+ */
 export async function req(url, { method = 'GET', headers = {}, body, timeout = 20000, stream = false, signal = null } = {}) {
   const started = Date.now();
   try {
-    checkUrl(url);   // 허용된 자리가 아니면 여기서 끝난다. 본문은 만들어지지도 않는다.
-    // 시간 초과와 '사용자가 Ctrl+C' 를 둘 다 듣는다. 둘 중 먼저 오는 쪽이 끊는다.
-    const sig = signal
-      ? (AbortSignal.any ? AbortSignal.any([AbortSignal.timeout(timeout), signal]) : signal)
-      : AbortSignal.timeout(timeout);
-    const res = await fetch(url, {
-      method,
-      headers,
+    const r = await 원시요청(url, {
+      method, headers, timeout, stream, signal,
       body: body === undefined ? undefined : JSON.stringify(body),
-      signal: sig,
-      redirect: 'follow',
     });
-    const ms = Date.now() - started;
-    if (stream) return { ok: res.ok, status: res.status, res, ms };
-
-    const text = await res.text();
-    let json = null;
-    try { json = JSON.parse(text); } catch {}
-    return { ok: res.ok, status: res.status, json, text, ms, headers: res.headers };
+    // 프록시가 407 로 막은 것은 통신 실패도 서버 답도 아니다. 사람 말 한 줄로 준다.
+    if (r.error) return { ok: false, status: r.status, error: r.error, json: r.json ?? null, text: r.text ?? '', headers: r.headers, ms: r.ms };
+    if (stream) return { ok: r.ok, status: r.status, res: r.res, ms: r.ms };
+    return { ok: r.ok, status: r.status, json: r.json, text: r.text, ms: r.ms, headers: r.headers };
   } catch (err) {
     const ms = Date.now() - started;
     // 막힌 것은 통신 실패와 다르다. 조용히 넘기면 자물쇠가 있는지도 모른다.
     if (err instanceof NetBlocked) throw err;
     // 사용자가 끊은 것도 실패가 아니다. 오류 화면을 띄우면 안 된다.
-    if (signal?.aborted) throw new Aborted();
-    return { ok: false, status: 0, error: normalizeError(err), ms };
+    if (err instanceof Aborted || signal?.aborted) throw new Aborted();
+    // 코드도 같이 준다. 사람 말(error)로는 "끊겼다" 와 "거부됐다" 를 가를 수 있지만
+    // 다시 불러도 되는지(backend/retry.js)는 코드로 가르는 것이 정확하다.
+    // 프록시가 터널을 거절한 것(407 등)은 상태 코드가 있다. 그 밖의 통신 실패는 0.
+    return { ok: false, status: err?.code === 'PROXY_CONNECT' ? (err.status ?? 0) : 0, error: normalizeError(err), code: 오류코드(err), ms };
   }
 }
 
-// 사용자가 Ctrl+C 로 끊었다는 뜻. 통신 오류와 구분하려고 따로 둔다.
-export class Aborted extends Error {
-  constructor() { super('사용자가 중단했습니다'); this.name = 'Aborted'; }
+const 되돌림상태 = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * 요청 하나, 날것 그대로. 몸은 문자열·버퍼를 그대로 보내고, 오류는 그대로 던진다.
+ * req() 와 WebFetch(tools/webfetch.js), 플러그인 받기(plugins/manage.js)가 이걸 쓴다 —
+ * fetch 를 직접 부르는 자리는 이 파일 밖에 없어야 한다.
+ *
+ * @param {object} o
+ *   되돌림(다음URL) — 되돌림을 따라가기 **전에** 부른다. 던지면 안 따라간다.
+ *                    부르는 쪽이 제 규칙(사내망 거절 등)을 여기서 건다.
+ * @returns 흘려 받기면 { ok, status, headers, res: { body(getReader), headers, text() }, ms }
+ *          아니면       { ok, status, headers, bytes, text, json, ms }
+ *          프록시가 407 로 막으면 { ok:false, status:407, error } (몸은 없다)
+ */
+export async function 원시요청(url, { method = 'GET', headers = {}, body, timeout = 20000, stream = false, signal = null, 되돌림 = null, 최대홉 = 5 } = {}) {
+  const started = Date.now();
+  let 지금 = String(url);
+  let 방법 = method;
+  let 몸 = body;
+  let 머리 = { ...headers };
+  for (let 홉 = 0; ; 홉++) {
+    const 프록시 = 프록시고르기(지금);
+    checkUrl(지금, 프록시?.url ?? null);   // 허용된 자리가 아니면 여기서 끝난다. 본문은 만들어지지도 않는다.
+    const r = 프록시
+      ? await 프록시로(지금, { method: 방법, headers: 머리, body: 몸, timeout, stream, signal, 프록시 })
+      : await 직접(지금, { method: 방법, headers: 머리, body: 몸, timeout, stream, signal });
+
+    const loc = 되돌림상태.has(r.status) ? r.headers?.get?.('location') : null;
+    if (loc && 홉 < 최대홉) {
+      let 다음;
+      try { 다음 = new URL(loc, 지금); } catch { return { ...r, ms: Date.now() - started }; }
+      await r.버리기?.();               // 안 읽은 몸을 두고 다음 요청을 보내면 연결이 남는다.
+      되돌림?.(다음);
+      // fetch 가 하는 대로: 303 은 GET 으로, POST 의 301·302 도 GET 으로, 307·308 은 그대로.
+      if (r.status === 303 || ((r.status === 301 || r.status === 302) && 방법 !== 'GET' && 방법 !== 'HEAD')) {
+        방법 = 'GET';
+        몸 = undefined;
+      }
+      // 다른 집으로 가면 열쇠 머리말은 뗀다 — 게이트웨이 열쇠가 딴 집으로 가면 안 된다.
+      if (다음.origin !== new URL(지금).origin) {
+        for (const k of Object.keys(머리)) {
+          if (/^(authorization|x-api-key|api-key|proxy-authorization|cookie)$/i.test(k)) delete 머리[k];
+        }
+      }
+      지금 = 다음.href;
+      continue;
+    }
+    return { ...r, ms: Date.now() - started };
+  }
+}
+
+/**
+ * 흘려 받는 몸을 상한까지만 읽는다. 넘으면 끊고 null — 다 받아 놓고 버리지 않는다.
+ * WebFetch(2MB)와 플러그인 받기(64MB)가 쓴다. 상한 없는 읽기는 한 자리(어댑터의 JSON 답)만 남긴다.
+ */
+export async function 몸읽기(body, 상한) {
+  const reader = body.getReader();
+  const 조각 = [];
+  let 크기 = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    크기 += value.length;
+    if (크기 > 상한) {
+      try { await reader.cancel(); } catch { /* 끊는 중 오류는 그만 */ }
+      return null;
+    }
+    조각.push(Buffer.from(value));
+  }
+  return Buffer.concat(조각);
+}
+
+// 시간 초과와 '사용자가 Ctrl+C' 를 둘 다 듣는다. 둘 중 먼저 오는 쪽이 끊는다.
+function 신호(timeout, signal) {
+  const 시계 = AbortSignal.timeout(timeout);
+  if (!signal) return 시계;
+  return AbortSignal.any ? AbortSignal.any([시계, signal]) : signal;
+}
+
+// ── 직접 가는 길: fetch ─────────────────────────────────────────────────
+async function 직접(url, { method, headers, body, timeout, stream, signal }) {
+  const res = await fetch(url, { method, headers, body, signal: 신호(timeout, signal), redirect: 'manual' });
+  if (stream) {
+    return {
+      ok: res.ok, status: res.status, headers: res.headers, res,
+      버리기: async () => { try { await res.arrayBuffer(); } catch { /* 버리는 중 끊겨도 그만 */ } },
+    };
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const text = bytes.toString('utf8');
+  let json = null;
+  try { json = JSON.parse(text); } catch { /* 글로만 오는 서버도 있다 */ }
+  return { ok: res.ok, status: res.status, headers: res.headers, bytes, text, json };
+}
+
+// ── 프록시를 거치는 길: CONNECT 터널 / 절대 주소 ─────────────────────────
+function 프록시로(url, { method, headers, body, timeout, stream, signal, 프록시 }) {
+  const 대상 = new URL(url);
+  const 포트 = Number(대상.port || (대상.protocol === 'https:' ? 443 : 80));
+  const sig = 신호(timeout, signal);
+  // 끊긴 까닭은 신호를 보고 가른다 — 사람이 끊은 것과 시계가 끊은 것은 화면에서 다른 말이다.
+  const 왜끊겼나 = () => (signal?.aborted
+    ? new Aborted()
+    : Object.assign(new Error('시간 초과 — 응답이 없습니다'), { name: 'TimeoutError', code: 'TimeoutError' }));
+
+  return new Promise((resolve, reject) => {
+    let rq = null;
+    let 응답 = null;
+    let 끝났나 = false;
+    const 정리 = () => sig.removeEventListener('abort', 끊기);
+    const 실패 = (e, 프록시탓 = false) => {
+      if (끝났나) return;
+      끝났나 = true;
+      정리();
+      if (프록시탓) e.프록시 = 프록시.url;
+      reject(e);
+    };
+    const 끊기 = () => {
+      const e = 왜끊겼나();
+      // 이미 답을 돌려준 뒤(흘려 받는 중)라도 소켓은 끊는다 — 읽는 쪽이 **이 까닭**으로 멈춘다.
+      // 요청만 끊으면 읽는 쪽에는 'aborted' 라는 맹숭한 오류가 간다. 답 쪽을 먼저 그 까닭으로 끊는다.
+      if (응답) { try { 응답.destroy(e); } catch { /* 이미 닫혔으면 그만 */ } }
+      if (rq) { try { rq.destroy(e); } catch { /* 이미 닫혔으면 그만 */ } }
+      실패(e);
+    };
+    sig.addEventListener('abort', 끊기, { once: true });
+
+    const 받기 = (res) => {
+      응답 = res;
+      const 머리 = new Headers();
+      for (const [k, v] of Object.entries(res.headers)) {
+        if (v != null) 머리.set(k, Array.isArray(v) ? v.join(', ') : String(v));
+      }
+      const ok = res.statusCode >= 200 && res.statusCode < 300;
+      const 마침 = (값) => { if (끝났나) return; 끝났나 = true; 정리(); resolve(값); };
+      // 프록시가 인증을 요구한 것은 서버 답이 아니다. 사람 말로 바꿔 준다.
+      if (res.statusCode === 407) {
+        res.resume();
+        return 마침({ ok: false, status: 407, headers: 머리, bytes: Buffer.alloc(0), text: '', json: null, error: 인증말(머리.get('proxy-authenticate'), 프록시) });
+      }
+      if (stream && ok) {
+        /*
+         * 흘려 받는 동안에는 끊기 귀를 **계속 열어 둔다.** 머리말이 왔다고 귀를 닫으면
+         * 그 뒤의 Ctrl+C 가 소켓을 못 끊어서, 답이 다 올 때까지 화면이 안 멈춘다
+         * (평가에서 잡혔다 — 직접 갈 때는 2ms, 프록시로 갈 때는 안 멈췄다).
+         * 몸이 다 오거나 끊기면(close) 그때 닫는다.
+         */
+        const body = Readable.toWeb(res);
+        res.once('close', 정리);
+        if (!끝났나) { 끝났나 = true; resolve({
+          ok, status: res.statusCode, headers: 머리,
+          res: { body, headers: 머리, text: () => 다읽기(res) },
+          버리기: async () => { try { res.resume(); await new Promise((r) => res.once('close', r)); } catch { /* 그만 */ } },
+        }); }
+        return;
+      }
+      다읽기(res).then((text) => {
+        const bytes = Buffer.from(text, 'utf8');
+        let json = null;
+        try { json = JSON.parse(text); } catch { /* 글로만 오는 서버도 있다 */ }
+        // 흘려 받으려다 거절당한 것도 여기로 온다. adapter 의 거절읽기가 res.text() 를 부른다.
+        마침({ ok, status: res.statusCode, headers: 머리, bytes, text, json, res: { headers: 머리, text: async () => text } });
+      }, (e) => 실패(e));
+    };
+
+    (async () => {
+      try {
+        if (대상.protocol === 'https:') {
+          const socket = await 터널(대상.hostname, 포트, 프록시, sig, 왜끊겼나);
+          if (sig.aborted) { socket.destroy(); return 끊기(); }
+          // agent 를 **주지 않아야** createConnection 을 쓴다. agent: false 를 주면 Node 가
+          // 새 Agent 를 만들어 제 소켓으로 직접 나가고, 터널 소켓은 열린 채 버려진다 —
+          // 프록시를 거치지 않았는데 답은 오니(대상이 닿는 자리면) 알아채기 어렵다.
+          rq = httpsRequest({
+            createConnection: () => socket,
+            host: 대상.hostname, port: 포트, path: 대상.pathname + 대상.search, method,
+            headers: { ...headers, Host: 대상.host },
+          }, 받기);
+        } else {
+          const 머리 = { ...headers, Host: 대상.host };
+          if (프록시.auth) 머리['Proxy-Authorization'] = 프록시.auth;
+          rq = httpRequest({ host: 프록시.host, port: 프록시.port, agent: false, path: url, method, headers: 머리 }, 받기);
+          rq.once('error', (e) => 실패(e, /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ECONNRESET/.test(e?.code ?? '')));
+        }
+        if (sig.aborted) return 끊기();
+        rq.once('error', (e) => 실패(e));
+        if (body !== undefined) rq.write(body);
+        rq.end();
+      } catch (e) { 실패(e); }
+    })();
+  });
+}
+
+/*
+ * CONNECT 로 터널을 뚫고 그 위에 TLS 를 올린다. 소켓 하나를 돌려준다.
+ *
+ * SNI 는 이름일 때만 붙인다. IP 에 붙이면 Node 가 경고를 낸다(DEP0123). IP 대상은
+ * host 로 넘겨서 인증서의 IP SAN 과 견주게 한다.
+ */
+function 터널(hostname, port, 프록시, sig, 왜끊겼나) {
+  return new Promise((resolve, reject) => {
+    const 머리 = { Host: `${hostname}:${port}` };
+    if (프록시.auth) 머리['Proxy-Authorization'] = 프록시.auth;
+    const rq = httpRequest({
+      host: 프록시.host, port: 프록시.port, agent: false,
+      method: 'CONNECT', path: `${hostname}:${port}`, headers: 머리,
+    });
+    const 끊기 = () => rq.destroy(왜끊겼나());
+    sig.addEventListener('abort', 끊기, { once: true });
+    const 정리 = () => sig.removeEventListener('abort', 끊기);
+
+    rq.once('connect', (res, socket, head) => {
+      정리();
+      if (res.statusCode !== 200) {
+        socket.destroy();
+        const e = new Error(res.statusCode === 407
+          ? 인증말(res.headers['proxy-authenticate'], 프록시)
+          : `프록시(${프록시.url})가 터널을 거절했습니다 (HTTP ${res.statusCode})`);
+        e.status = res.statusCode;
+        e.code = 'PROXY_CONNECT';
+        return reject(e);
+      }
+      if (head?.length) socket.unshift(head);
+      const 이름 = /^[\d.]+$|:/.test(hostname) ? undefined : hostname;
+      const tls = tlsConnect({ socket, host: hostname, servername: 이름 }, () => resolve(tls));
+      tls.once('error', reject);     // 대상 인증서 문제 — 프록시 탓이 아니라 표시를 안 붙인다
+      // TLS 층이 닫혀도 밑의 프록시 소켓은 저절로 안 닫힌다. 그대로 두면 요청마다 소켓이
+      // 하나씩 남아 프로세스가 안 끝난다 (deel run 이 답을 찍고도 안 나가는 모양이 된다).
+      tls.once('close', () => socket.destroy());
+    });
+    rq.once('error', (e) => { 정리(); e.프록시 = 프록시.url; reject(e); });
+    rq.end();
+  });
+}
+
+function 다읽기(res) {
+  return new Promise((resolve, reject) => {
+    const 조각 = [];
+    res.on('data', (d) => 조각.push(d));
+    res.once('end', () => resolve(Buffer.concat(조각).toString('utf8')));
+    res.once('error', reject);
+  });
+}
+
+// 프록시가 407 을 줬을 때 사람이 칠 것까지 적어 준다. NTLM·Negotiate 는 못 하니 그렇다고 말한다.
+// 칠 자리는 **지금 그 프록시를 읽어 온 곳**이다 — HTTP_PROXY 로 정한 사람에게 HTTPS_PROXY 를
+// 고치라고 하면 고쳐도 안 바뀐다 (평가에서 잡혔다).
+function 인증말(도전, 프록시) {
+  const s = String(도전 ?? '');
+  if (/ntlm|negotiate/i.test(s)) {
+    return `프록시(${프록시.url})가 ${/ntlm/i.test(s) ? 'NTLM' : 'Negotiate'} 인증을 요구합니다 — 이 방식은 지원하지 않습니다.`
+      + ' 사내 담당자에게 Basic 인증이나 인증 없는 프록시 주소를 문의하세요.';
+  }
+  const 주소 = `http://user:pw@${프록시.host}:${프록시.port}`;
+  const 자리 = 프록시.출처 === 'config'
+    ? `설정 파일의 "proxy": "${주소}"`
+    : `${프록시.출처 ?? 'HTTPS_PROXY'}=${주소}`;
+  return `프록시(${프록시.url})가 인증을 요구합니다 (407${s ? ` · ${s.slice(0, 60)}` : ''})`
+    + ` — 프록시 주소에 user:pw@ 를 넣으세요: ${자리}`;
+}
+
+// fetch 가 던진 것에서 코드 하나를 뽑는다. undici 는 원인을 cause 에 싸서 준다.
+function 오류코드(err) {
+  return err?.cause?.code ?? err?.code ?? err?.cause?.name ?? err?.name ?? null;
 }
 
+// fetch 는 무슨 일이든 'fetch failed' 라고만 말하고 까닭은 cause 에 숨긴다. 그래서
+// 말(m)만 보지 않고 코드도 본다 — 안 그러면 DNS 실패도 "주소·포트·프록시를 확인하세요" 가 된다.
 function normalizeError(err) {
   const m = String(err?.message ?? err);
-  if (err?.name === 'TimeoutError' || /timed? ?out/i.test(m)) return '시간 초과 — 응답이 없습니다';
-  if (/ENOTFOUND|getaddrinfo/i.test(m)) return '주소를 찾을 수 없습니다 (DNS)';
-  if (/ECONNREFUSED/i.test(m)) return '연결이 거부되었습니다 (서버가 꺼져 있거나 포트가 다릅니다)';
-  if (/ECONNRESET/i.test(m)) return '연결이 끊겼습니다';
-  if (/certificate|SELF_SIGNED|UNABLE_TO_VERIFY/i.test(m)) return '인증서 문제 — 사내 인증서라면 NODE_EXTRA_CA_CERTS 가 필요합니다';
-  if (/fetch failed/i.test(m)) return '연결 실패 — 주소·포트·프록시를 확인하세요';
-  return m;
+  const 코드 = String(오류코드(err) ?? '');
+  const 기본 = (() => {
+    if (err?.code === 'PROXY_CONNECT') return m;
+    if (err?.name === 'TimeoutError' || 코드 === 'TimeoutError' || /timed? ?out/i.test(m)) return '시간 초과 — 응답이 없습니다';
+    if (/ENOTFOUND|EAI_AGAIN/.test(코드) || /ENOTFOUND|getaddrinfo/i.test(m)) return '주소를 찾을 수 없습니다 (DNS)';
+    if (코드 === 'ECONNREFUSED' || /ECONNREFUSED/i.test(m)) return '연결이 거부되었습니다 (서버가 꺼져 있거나 포트가 다릅니다)';
+    // 받아 놓고 끊은 것 — 서버가 꺼진 것과 다르다. "주소를 확인하라" 는 틀린 조언이다.
+    if (/ECONNRESET|EPIPE|UND_ERR_SOCKET/.test(코드) || /ECONNRESET|other side closed/i.test(m)) return '서버가 연결을 끊었습니다';
+    if (/certificate|SELF_SIGNED|UNABLE_TO_VERIFY|CERT_/i.test(m + ' ' + 코드)) return '인증서 문제 — 사내 인증서라면 NODE_EXTRA_CA_CERTS 가 필요합니다';
+    /*
+     * 헤더에 한글이 섞였다.
+     *
+     * HTTP 헤더는 Latin-1 만 실린다. 열쇠에 한글이나 특수문자가 한 글자라도
+     * 있으면 요청이 만들어지지도 않고 `ByteString` 소리를 하는 오류가 난다 —
+     * 그대로 보여 주면 사람은 서버를 의심하고 방화벽부터 뒤진다. 실제로는
+     * 열쇠를 붙여넣다 한글이 섞였거나 따옴표가 딸려 온 것이다.
+     */
+    /*
+     * `invalid header value` 도 같이 잡는 이유 — **여기가 열쇠 유출 자리다.**
+     *
+     * 헤더 값이 못 실릴 때 런타임이 내는 말이 두 가지다.
+     *   한글이 섞였을 때   Cannot convert … ByteString … character at index 23
+     *   줄바꿈·NUL 이 섞였을 때  Headers.append: "sk-진짜열쇠…" is an invalid header value.
+     *
+     * 뒤엣것은 **열쇠를 그대로 따옴표 안에 넣어서** 말한다. 그 문구는 화면에도
+     * 뜨고 진단 보고서 파일에도 적히는데, 그 파일은 "사내망에서 돌렸다면 이것만
+     * 가져오시면 됩니다" 라고 우리가 권하는 파일이다. 열쇠를 파일에 안 남기려고
+     * 잠금장치까지 붙여 놓고, 오류 한 줄로 평문으로 흘리는 셈이었다.
+     *
+     * 그래서 두 가지를 한 자리에서 잡아 **우리 문장으로 갈아 끼운다.** 원문을
+     * 안 보여 주는 것이 여기서는 친절이 아니라 안전이다.
+     */
+    if (/ByteString|character at index|invalid header (value|name)/i.test(m)) return '열쇠(또는 헤더)에 한글·특수문자가 섞여 있습니다 — API 키는 영문·숫자만 실립니다. 붙여넣을 때 따옴표나 줄바꿈이 딸려 오지 않았는지 보세요';
+    if (/fetch failed/i.test(m)) return '연결 실패 — 주소·포트·프록시를 확인하세요';
+    return m;
+  })();
+  // 프록시까지 못 간 것은 게이트웨이 탓이 아니다. 어느 프록시였는지 적어야 사람이 고친다.
+  if (err?.프록시 && err?.code !== 'PROXY_CONNECT') return `프록시(${err.프록시})에 닿지 못했습니다 — ${기본}`;
+  return 기본;
 }
 
 // 게이트웨이 앞단 프록시가 자격증명을 받아오다 실패한 것을 알아본다.

package/src/backend/probe.js

@@ -6,6 +6,8 @@
 //   skip 앞 검사가 실패해 확인 불가
 import { req, headersFor, serverMessage } from './http.js';
 import { probeCtx } from './ctxsize.js';
+import { 눈검사메시지 } from './vision.js';
+import { 주소붙이기 } from './adapter.js';
 
 const READ_TOOL = {
   type: 'function',
@@ -59,6 +61,7 @@ const SKIPPED = [
   ['tools', '도구 호출'],
   ['toolresult', '도구 결과 되돌리기'],
   ['json', '구조적 출력'],
+  ['vision', '그림 보기'],
   ['think', '추론 강도 조절'],
   ['ctx', '컨텍스트 길이'],
 ];
@@ -67,7 +70,17 @@ export async function probe(conn, onStep = () => {}) {
   const { kind: shape, base, auth, model } = conn;
   const key = conn.key ?? '';
   const H = () => headersFor(auth, key);
-  const url = (p) => `${base}${p}`;
+  /*
+   * 물음표 뒤를 끝에 남겨야 한다 (adapter.js 의 주소붙이기).
+   *
+   * 이 한 줄이 예전에 `${base}${p}` 였다. Azure base 에는 `?api-version=` 이
+   * 붙어 있어서, 그대로 이으면
+   * `.../deployments/gpt-4o?api-version=2024-10-21/chat/completions` 가 된다.
+   * 그러면 **설치 화면이 제 검사에 통째로 실패한다** — 기본 대화가 안 되니
+   * 나머지 일곱 칸이 다 '확인 불가' 로 건너뛰어지고, 프로필에는 스트리밍도
+   * 도구 호출도 안 된다고 적힌다. 붙기는 붙는데 반쪽짜리로 붙는다.
+   */
+  const url = (p) => 주소붙이기(base, p);
   const results = [];
   const facts = { shape, base, auth, model };
 
@@ -283,6 +296,40 @@ export async function probe(conn, onStep = () => {}) {
   });
   facts.json = jsonOk;
 
+  /*
+   * 6.5 그림 — 이 모델이 그림을 볼 수 있느냐.
+   *
+   * 이름으로 짐작하지 않는다. 사내 게이트웨이는 `gpt-4o` 라는 이름 뒤에
+   * 무엇이든 걸어 둘 수 있고, 로컬에 받아 둔 llava 계열은 이름이 제각각이다.
+   * 한 번 물어보면 확실해지는 것을 짐작할 이유가 없다.
+   *
+   * 흰 점 하나짜리 1×1 PNG 로 묻는다 (vision.js). 무엇이 찍혀 있을지 모르는
+   * 진짜 화면을 확인하자고 바깥으로 내보낼 수는 없다.
+   *
+   * 답의 내용은 안 본다. 흰 점 하나를 보고 무슨 말을 하든 상관없고, 우리가
+   * 알고 싶은 것은 **서버가 그림이 든 메시지를 받아 주느냐** 하나다.
+   * 못 받는 서버는 400 이나 415 로 거절한다.
+   */
+  const 눈 = await call({
+    ...quiet,
+    messages: [눈검사메시지(shape)],
+    maxTokens: 32,
+    timeout: 60000,
+  });
+  const 눈있음 = !!(눈.ok && extract(shape, 눈.json).content);
+  add({
+    id: 'vision',
+    label: '그림 보기',
+    status: 눈있음 ? 'ok' : 눈.ok ? 'warn' : 'no',
+    detail: 눈있음
+      ? `1×1 PNG 를 받아서 답함 — Read·@ 로 화면 사진을 보여 줄 수 있습니다`
+      : 눈.ok
+        ? '그림을 받긴 했는데 답이 비었습니다 — 안 보이는 것으로 칩니다'
+        : `${serverMessage(눈)} — 그림은 안 보냅니다`,
+    ms: 눈.ms ?? 0,
+  });
+  facts.vision = 눈있음;
+
   // 7. 추론 강도 조절 — 낮음/높음이 실제로 다른 결과를 내느냐.
   //    상한에 걸리면 둘 다 같은 숫자가 나와 비교가 무의미해진다. 넉넉히 준다.
   const THINK_CAP = 1500;

package/src/backend/proxy.js

@@ -0,0 +1,151 @@
+// 프록시를 거칠지, 거친다면 어디로 갈지를 정한다. 소켓은 안 만든다 — 그건 http.js 의 일이다.
+//
+// 왜 필요한가:
+//   README 는 "프록시 뒤면 HTTPS_PROXY 를 주라" 고 적어 놨었다. 그런데 Node 의 fetch 는
+//   그 환경변수를 **안 본다.** 직접 재 봤다 — HTTP_PROXY 를 주고 fetch 를 하니 프록시는
+//   요청을 한 건도 못 봤고, 대상 서버로 곧장 갔다. (Node 24 부터 NODE_USE_ENV_PROXY=1
+//   로 켜면 보긴 하는데, 프로세스가 뜨기 전에 걸어야 하고 Node 20·22 에는 없다.)
+//   바깥으로 직접 못 나가는 사내망에서는 그게 "연결 실패" 한 줄로 끝났다. 적혀 있는
+//   탈출구가 실제로는 막혀 있는 것이 제일 나쁘다.
+//
+// 어느 것이 이기나:
+//   1) 설정 파일의 proxy — 'none' 이면 환경변수가 있어도 안 쓴다. 회사 PC 는 프록시
+//      환경변수가 전역으로 박혀 있는데, 그걸 못 끄면 게이트웨이가 사내망 안에 있어도
+//      프록시로 돌아 나간다.
+//   2) 환경변수 — https 대상은 HTTPS_PROXY, http 대상은 HTTP_PROXY, 둘 다 없으면 ALL_PROXY.
+//      소문자 이름도 본다 (리눅스 도구들은 소문자를 먼저 본다).
+//   3) NO_PROXY 에 걸리면 직접 — `*` 는 전부, `.corp.com`·`corp.com` 은 뒤가 맞으면,
+//      `host:port` 는 포트까지, IPv4 는 그대로.
+//   4) 그리고 **루프백은 언제나 직접 간다.** localhost 의 Ollama 가 프록시로 나가서
+//      죽는 것을 막는 규칙이다. curl 은 안 그러지만 윈도우·브라우저는 다 이렇게 한다.
+//
+// 지원하지 않는 것은 그렇다고 말한다: https:// 프록시, socks5://, PAC 파일, 윈도우
+// 레지스트리 프록시, NTLM/Negotiate 인증. 조용히 직접 가는 것보다 낫다.
+
+const 루프백 = (h) => {
+  const s = String(h ?? '').toLowerCase().replace(/^\[|\]$/g, '');
+  return s === 'localhost' || s === '::1' || /^127\./.test(s) || s === '0.0.0.0';
+};
+
+/** 'http://user:pass@host:8080' → { url, host, port, auth }. 못 읽으면 { 탈 } */
+export function 프록시읽기(값) {
+  const s = String(값 ?? '').trim();
+  if (!s) return null;
+  let u;
+  try { u = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(s) ? s : `http://${s}`); } catch { return { 탈: `프록시 주소를 읽을 수 없습니다: ${s}` }; }
+  if (u.protocol !== 'http:') {
+    return { 탈: `${u.protocol}// 프록시는 지원하지 않습니다 (http:// 프록시만 됩니다): ${s}` };
+  }
+  const auth = u.username
+    ? `Basic ${Buffer.from(`${decodeURIComponent(u.username)}:${decodeURIComponent(u.password)}`).toString('base64')}`
+    : null;
+  return {
+    url: `http://${u.host}`,
+    host: u.hostname,
+    port: Number(u.port || 80),
+    auth,
+  };
+}
+
+/** NO_PROXY 한 줄을 항목 배열로. */
+export function 우회목록(값) {
+  return String(값 ?? '').split(',').map((x) => x.trim().toLowerCase()).filter(Boolean);
+}
+
+/** 이 대상이 NO_PROXY 에 걸리나. */
+export function 우회할까(hostname, port, 목록) {
+  const h = String(hostname ?? '').toLowerCase().replace(/^\[|\]$/g, '');
+  const p = Number(port);
+  for (const 항목 of 목록 ?? []) {
+    if (항목 === '*') return true;
+    let 이름 = 항목;
+    let 포트 = null;
+    const m = /^(.*):(\d+)$/.exec(항목);
+    if (m && !/^\[?[0-9a-f:]+\]?$/i.test(항목)) { 이름 = m[1]; 포트 = Number(m[2]); }
+    if (포트 !== null && 포트 !== p) continue;
+    이름 = 이름.replace(/^\*/, '').replace(/^\./, '');
+    if (!이름) continue;
+    if (h === 이름 || h.endsWith(`.${이름}`)) return true;
+  }
+  return false;
+}
+
+let 지금 = { 프록시: null, 출처: null, 우회: [], 로컬우회: true, 탈: null };
+
+/**
+ * 켤 때 한 번 정한다. 설정이 환경변수를 이긴다.
+ * @param {{ env?: object, config?: object|null, 로컬우회?: boolean }} 자리
+ *   로컬우회 는 검사만 false 로 준다 — 진짜 실행에서는 루프백이 언제나 직접이다.
+ */
+export function 프록시정하기({ env = process.env, config = null, 로컬우회 = true } = {}) {
+  const 읽기 = (k) => env[k] ?? env[k.toLowerCase()] ?? null;
+  const 우회 = 우회목록(읽기('NO_PROXY'));
+  const 정한값 = config?.proxy;
+  let 고른것 = null;
+  let 출처 = null;
+  let 탈 = null;
+
+  if (정한값 === 'none' || 정한값 === false) {
+    // 일부러 끈 것. 환경변수는 안 본다.
+  } else if (typeof 정한값 === 'string' && 정한값.trim()) {
+    고른것 = 프록시읽기(정한값);
+    출처 = 'config';
+  } else {
+    // 환경변수는 대상 규격에 따라 다르므로 여기서는 둘 다 들고 있다가 고를 때 본다.
+    고른것 = {
+      https: 읽기('HTTPS_PROXY') ? 프록시읽기(읽기('HTTPS_PROXY')) : null,
+      http: 읽기('HTTP_PROXY') ? 프록시읽기(읽기('HTTP_PROXY')) : null,
+      all: 읽기('ALL_PROXY') ? 프록시읽기(읽기('ALL_PROXY')) : null,
+      출처: { https: 'HTTPS_PROXY', http: 'HTTP_PROXY', all: 'ALL_PROXY' },
+    };
+    출처 = 'env';
+    if (!고른것.https && !고른것.http && !고른것.all) { 고른것 = null; 출처 = null; }
+  }
+  if (고른것?.탈) { 탈 = 고른것.탈; 고른것 = null; 출처 = null; }
+  for (const k of ['https', 'http', 'all']) {
+    if (고른것?.[k]?.탈) { 탈 = 고른것[k].탈; 고른것[k] = null; }
+  }
+  지금 = { 프록시: 고른것, 출처, 우회, 로컬우회, 탈 };
+  return 프록시설정();
+}
+
+/** 지금 정해진 것 (화면·심사서용). 비밀번호는 안 낸다. */
+export function 프록시설정() {
+  const 것 = 지금.프록시;
+  const 하나 = (p, 출처) => (p ? { url: p.url, 출처, 인증: !!p.auth } : null);
+  let 목록 = [];
+  if (지금.출처 === 'config' && 것) 목록 = [하나(것, 'config')];
+  else if (지금.출처 === 'env' && 것) {
+    목록 = [
+      것.https ? 하나(것.https, 'HTTPS_PROXY') : null,
+      것.http ? 하나(것.http, 'HTTP_PROXY') : null,
+      것.all ? 하나(것.all, 'ALL_PROXY') : null,
+    ].filter(Boolean);
+  }
+  return { 프록시들: 목록, 우회: 지금.우회.slice(), 로컬우회: 지금.로컬우회, 탈: 지금.탈, 켜짐: 목록.length > 0 };
+}
+
+/**
+ * 이 주소로 갈 때 거칠 프록시. 없으면 null (직접 간다).
+ * @returns {{ url, host, port, auth, 출처 }|null}
+ */
+export function 프록시고르기(url) {
+  const 것 = 지금.프록시;
+  if (!것) return null;
+  let u;
+  try { u = new URL(url); } catch { return null; }
+  if (지금.로컬우회 && 루프백(u.hostname)) return null;
+  const 포트 = Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+  if (우회할까(u.hostname, 포트, 지금.우회)) return null;
+
+  if (지금.출처 === 'config') return { ...것, 출처: 'config' };
+  const k = u.protocol === 'https:' ? 'https' : 'http';
+  const p = 것[k] ?? 것.all;
+  if (!p) return null;
+  return { ...p, 출처: 것[k] ? 것.출처[k] : 것.출처.all };
+}
+
+/** 검사용 — 아무것도 안 정한 상태로. */
+export function 프록시지우기() {
+  지금 = { 프록시: null, 출처: null, 우회: [], 로컬우회: true, 탈: null };
+}