coxpit 4.7.0 → 5.0.0

package/.env.example

@@ -3,8 +3,10 @@ COXPIT_HOST=127.0.0.1
 COXPIT_PORT=8210
 COXPIT_DB=./coxpit.db
 
-# 인증 게이트(basic). 프로덕션은 앞단에 Cloudflare Access / Tailscale 권장.
-COXPIT_AUTH_USER=admin
+# 접근키(access-key) 인증. 인증은 노출 바인드일 때만 적용된다:
+#  - COXPIT_HOST=127.0.0.1 (기본) → 로컬 신뢰, 로그인 없음(무마찰).
+#  - COXPIT_HOST=0.0.0.0 등 노출 → 브랜디드 언락/셋업 페이지 + 세션 쿠키로 접근키 요구.
+# COXPIT_AUTH_PASS = 접근키(back-compat, 유저명 없음). 비우면 저장된 키 또는 첫 실행 셋업.
 COXPIT_AUTH_PASS=
-# 로컬 개발 시 인증 끄기:
+# 인증을 완전히 끄고 앞단 게이트웨이(Cloudflare Access / Tailscale)에 위임:
 # COXPIT_AUTH_DISABLED=1

package/README.md

@@ -74,8 +74,8 @@ Your keys and login never touch coxpit's config or database.
 |---|---|---|
 | `COXPIT_HOST` / `COXPIT_PORT` | `127.0.0.1` / `8210` | daemon bind |
 | `COXPIT_DB` | `~/.coxpit/coxpit.db` | SQLite (libSQL) file (a legacy `./coxpit.db` in the cwd is still honored) |
-| `COXPIT_AUTH_PASS` / `COXPIT_AUTH_USER` | — / `admin` | basic auth. **Empty pass = all requests rejected** (fail-closed) — set it, or use `COXPIT_AUTH_DISABLED=1` for local dev |
-| `COXPIT_AUTH_DISABLED` | — | `1` disables auth (local dev only) |
+| `COXPIT_AUTH_PASS` | — | access key (back-compat, key-only). If set on an **exposed** bind, the branded unlock page asks for this key — no username. Empty = use the stored key, or first-run setup |
+| `COXPIT_AUTH_DISABLED` | — | `1` forces auth **off** (delegate to a front gateway like Cloudflare Access / Tailscale) |
 | `COXPIT_SSH_KEY` | — | private key for remote machines (else ssh defaults/agent) |
 | `COXPIT_AGENT_REAL` | — | `1` = real agent CLI by default (credits!) |
 | `COXPIT_AGENT_BIN` | `claude` | Claude Code command |
@@ -86,7 +86,19 @@ Your keys and login never touch coxpit's config or database.
 | `COXPIT_WEBHOOK_URL` | — | POSTs `{event:"run.settled",run:{...}}` when a run finishes — wire it to Telegram, Slack, anything |
 | `COXPIT_PUBLIC_URL` | — | if set, the webhook payload adds `url: <base>/?run=<id>` — tap it on your phone and the board opens that run |
 
-Running on the open internet? Put it behind your own front door (Tailscale, Cloudflare Access, a reverse proxy with TLS) and keep basic auth on — it exposes shells.
+Running on the open internet? Put it behind your own front door (Tailscale, Cloudflare Access, a reverse proxy with TLS) and keep the access key on — it exposes shells.
+
+## Access key & remote access
+
+Coxpit gates itself with a single **access key** (one owner, no accounts, no username) — but only when it's **exposed**:
+
+- **Loopback bind** (`COXPIT_HOST=127.0.0.1`, the default) is trusted-local: `npx coxpit` on your own machine is zero-friction, no login page, no key.
+- **Exposed bind** (`COXPIT_HOST=0.0.0.0` or a routable IP) requires the key. First boot with no key opens a **branded setup page** ("Protect this coxpit — set an access key"). To prove you own the box, setup needs the **one-time setup token** printed to the daemon log (Jupyter-style) — *unless* the request is genuinely local (`http://127.0.0.1` with no proxy in front). A request arriving through a tunnel must use the token, so a stranger hitting a fresh public daemon can't claim it.
+- After setup you **unlock once per device** via the same page (session cookie, "Remember this device" = 30 days). No native browser popup — unauthorized API calls just get `401` with no `WWW-Authenticate`.
+- **Back-compat:** set `COXPIT_AUTH_PASS` and that value *is* the key — the resident keeps working, now entered on the branded page (no username).
+- **Reset the key:** `coxpit reset-key` (or `rm ~/.coxpit/auth.json`) then restart → next boot is first-run setup again.
+
+Front it with **Cloudflare Access** or **Tailscale** for identity on top (set `COXPIT_AUTH_DISABLED=1` to delegate auth entirely to the gateway). The board's Remote access card detects your Tailscale and can put it on `https://<machine>.<tailnet>.ts.net` in one click.
 
 ## Platform support
 
@@ -127,3 +139,5 @@ issues privately per **[SECURITY.md](SECURITY.md)** (Coxpit exposes shells).
 ## License
 
 MIT
+
+Icons — [Lucide](https://lucide.dev) (ISC). Paths are inlined as an SVG `<symbol>` sprite (no runtime dependency); the ISC notice is kept in [`licenses/lucide.txt`](licenses/lucide.txt).

package/bin/coxpit.js

@@ -4,8 +4,9 @@
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { dirname, join } from 'node:path';
-import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { readFileSync, existsSync, rmSync } from 'node:fs';
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const entry = join(root, 'src', 'index.ts');
@@ -23,17 +24,25 @@ if (args.includes('--help') || args.includes('-h')) {
 
 Usage:
   coxpit                 start the daemon (board at http://<host>:<port>)
+  coxpit reset-key       forget the stored access key (next boot = first-run setup)
   coxpit --version, -v   print version
   coxpit --help, -h      show this help
 
+Access-key auth:
+  On first boot with no key, open the board to set an access key (a one-time
+  setup token is printed to the log — needed unless you visit http://127.0.0.1
+  directly). After that you unlock once per device via the branded page (no
+  username). To change or clear the key, run "coxpit reset-key" and restart, or
+  delete ~/.coxpit/auth.json. Precedence: COXPIT_AUTH_DISABLED > COXPIT_AUTH_PASS
+  env (back-compat, key-only) > stored key > first-run setup.
+
 Configuration is env-only (a .env file in the cwd is loaded):
   COXPIT_HOST            bind host (default 127.0.0.1)
   COXPIT_PORT            bind port (default 8210)
   COXPIT_DB              SQLite (libSQL) file (default ~/.coxpit/coxpit.db)
-  COXPIT_AUTH_USER       basic auth user (default admin)
-  COXPIT_AUTH_PASS       basic auth password (empty = all requests rejected;
-                         set it, or COXPIT_AUTH_DISABLED=1 for local dev)
-  COXPIT_AUTH_DISABLED   1 disables auth (local dev only)
+  COXPIT_AUTH_PASS       access key (empty = stored key / first-run setup;
+                         env-mode is back-compat, entered on the branded page)
+  COXPIT_AUTH_DISABLED   1 disables auth (delegate to a front gateway)
   COXPIT_SSH_KEY         private key for remote machines (else ssh defaults/agent)
   COXPIT_AGENT_REAL      1 = real agent CLI by default (credits!)
   COXPIT_AGENT_BIN       agent command (default claude)
@@ -41,6 +50,21 @@ Configuration is env-only (a .env file in the cwd is loaded):
   process.exit(0);
 }
 
+// reset-key — 저장된 접근키(auth.json)를 지운다. 다음 부팅은 다시 첫 실행 셋업.
+// auth.json 은 DB 와 같은 폴더에 산다(COXPIT_DB 존중, 기본 ~/.coxpit).
+if (args[0] === 'reset-key') {
+  const dbEnv = process.env.COXPIT_DB;
+  const dir = dbEnv ? dirname(resolve(dbEnv)) : join(homedir(), '.coxpit');
+  const authPath = join(dir, 'auth.json');
+  if (existsSync(authPath)) {
+    rmSync(authPath);
+    console.log(`[coxpit] removed ${authPath} — next boot is first-run setup (set a new access key).`);
+  } else {
+    console.log(`[coxpit] no stored key at ${authPath} (nothing to reset).`);
+  }
+  process.exit(0);
+}
+
 // --import 의 bare 'tsx' 는 사용자 cwd 기준으로 해석돼 npx 실행에서 깨진다 —
 // 패키지 루트 기준으로 절대경로 해석해 넘긴다.
 const require_ = createRequire(join(root, 'package.json'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coxpit",
-  "version": "4.7.0",
+  "version": "5.0.0",
   "description": "Self-hosted cockpit for running a fleet of AI coding agents across your own machines — parallel worktree runs, live board, compare & merge, web terminal, design capture.",
   "type": "module",
   "license": "MIT",

package/src/auth.ts

@@ -1,29 +1,60 @@
 import type { FastifyRequest, FastifyReply } from 'fastify';
 import { config } from './config';
+import {
+  authMode, verifyKey, verifySession, readCookie, SESSION_COOKIE,
+} from './authkey';
+import { loginPageHTML } from './login';
 
 // /api/design/capture · /design/bookmarklet.js 는 외부 앱(북마클릿)에서 오므로
-// basic 헤더를 못 싣는다 — 라우트 자체가 캡처 키(?k=)를 검증한다.
+// 헤더/쿠키를 못 싣는다 — 라우트 자체가 캡처 키(?k=)를 검증한다.
 // /api/agent/subtasks 는 에이전트 Bearer 토큰(라우트 자체 검증), /share/* 는 토큰 URL 이 곧 능력.
-const EXEMPT = new Set(['/api/health', '/api/design/capture', '/design/bookmarklet.js', '/api/agent/subtasks']);
+// /api/auth/* 는 언락/셋업 자체라 게이트 앞이어야 한다(체험 전 인증 불가).
+const EXEMPT = new Set([
+  '/api/health', '/api/design/capture', '/design/bookmarklet.js', '/api/agent/subtasks',
+  '/api/auth/setup', '/api/auth/unlock', '/api/auth/logout',
+]);
 const EXEMPT_PREFIX = ['/share/'];
 
+/** 이 요청이 HTML 문서를 원하는 GET 인가(→ 팝업 대신 login/setup 페이지 서빙). */
+function wantsHtml(req: FastifyRequest): boolean {
+  if (req.method !== 'GET') return false;
+  const accept = String(req.headers['accept'] ?? '');
+  return accept.includes('text/html');
+}
+
 /**
- * 인증 게이트 — 현재 basic. 플러그형 좌석: 배포 시 앞단에 Cloudflare Access / Tailscale 을
- * 두는 것을 권장(그 경우 COXPIT_AUTH_DISABLED=1 로 내부 인증을 끄고 게이트웨이에 위임).
+ * 인증 게이트 — 접근키(access-key) 기반.
+ * 순서: DISABLED → pass · EXEMPT → pass · 유효한 세션 쿠키 → pass ·
+ *       유효한 Basic 헤더(자동화 back-compat, 키만) → pass · else 거부.
+ * 거부 시 HTML GET 은 login/setup 페이지(200), 그 외는 401(WWW-Authenticate 없음 → 팝업 없음).
  */
 export async function authGate(req: FastifyRequest, reply: FastifyReply): Promise<void> {
-  if (config.auth.disabled) return;
+  const m = authMode();
+  if (m.mode === 'disabled') return;
+
   const path = req.url.split('?')[0] ?? '';
   if (EXEMPT.has(path)) return;
   if (EXEMPT_PREFIX.some((p) => path.startsWith(p))) return;
 
+  // 세션 쿠키(언락 완료 기기) — 무상태 서명 검증.
+  const sess = readCookie(req.headers.cookie, SESSION_COOKIE);
+  if (sess && verifySession(sess, m)) return;
+
+  // Basic 헤더 back-compat(자동화 전용) — 유저명은 무시, 비밀번호 자리를 키로 검증.
   const h = req.headers.authorization ?? '';
-  if (h.startsWith('Basic ') && config.auth.pass !== '') {
-    const decoded = Buffer.from(h.slice(6), 'base64').toString('utf8');
-    const idx = decoded.indexOf(':');
-    const u = decoded.slice(0, idx);
-    const p = decoded.slice(idx + 1);
-    if (u === config.auth.user && p === config.auth.pass) return;
+  if (h.startsWith('Basic ')) {
+    try {
+      const decoded = Buffer.from(h.slice(6), 'base64').toString('utf8');
+      const idx = decoded.indexOf(':');
+      const p = idx >= 0 ? decoded.slice(idx + 1) : decoded;
+      if (verifyKey(p, m)) return;
+    } catch { /* malformed header → 아래에서 거부 */ }
+  }
+
+  // 거부 — HTML GET 은 페이지, 나머지는 401(팝업 없음).
+  if (wantsHtml(req)) {
+    await reply.type('text/html').code(200).send(loginPageHTML(m.mode === 'setup'));
+    return;
   }
-  await reply.header('WWW-Authenticate', 'Basic realm="coxpit"').code(401).send({ error: 'unauthorized' });
+  await reply.code(401).send({ error: 'unauthorized' });
 }

package/src/authkey.ts

@@ -0,0 +1,260 @@
+// 접근키(access-key) 인증의 저장·해시·쿠키 서명·레이트리밋 — 전부 node 내장 crypto(신규 deps 0).
+// 브라우저 basic-auth 팝업 대신 브랜디드 언락/셋업 페이지 + 서명된 세션 쿠키를 뒷받침한다.
+import fs from 'node:fs';
+import path from 'node:path';
+import { scryptSync, randomBytes, timingSafeEqual, createHmac } from 'node:crypto';
+import { config } from './config';
+
+// 저장 위치 = DB 와 같은 데이터 폴더(~/.coxpit). auth.json 은 해시만 담는다(평문 키 없음).
+const AUTH_PATH = path.join(path.dirname(path.resolve(config.dbPath)), 'auth.json');
+
+export interface StoredAuth {
+  algo: 'scrypt';
+  salt: string;      // hex
+  hash: string;      // hex (scrypt(key, salt))
+  cookieSecret: string; // hex — 세션 쿠키 HMAC 서명용
+}
+
+const SCRYPT_N = 16384;
+const SCRYPT_KEYLEN = 32;
+
+function scryptHex(key: string, saltHex: string): string {
+  return scryptSync(key, Buffer.from(saltHex, 'hex'), SCRYPT_KEYLEN, { N: SCRYPT_N, r: 8, p: 1 }).toString('hex');
+}
+
+/** 두 hex 문자열을 상수시간 비교(길이 방어 포함). */
+export function constantEqHex(aHex: string, bHex: string): boolean {
+  try {
+    const a = Buffer.from(aHex, 'hex');
+    const b = Buffer.from(bHex, 'hex');
+    if (a.length === 0 || a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
+let cache: StoredAuth | null | undefined; // undefined = 미로드, null = 파일 없음
+
+/** 저장된 인증(있으면). env-mode 여도 파일이 있을 수 있으나 precedence 는 authMode 가 결정. */
+export function loadStored(): StoredAuth | null {
+  if (cache !== undefined) return cache;
+  try {
+    const raw = fs.readFileSync(AUTH_PATH, 'utf8');
+    const j = JSON.parse(raw) as Partial<StoredAuth>;
+    if (j && j.algo === 'scrypt' && typeof j.salt === 'string' && typeof j.hash === 'string' && typeof j.cookieSecret === 'string') {
+      cache = { algo: 'scrypt', salt: j.salt, hash: j.hash, cookieSecret: j.cookieSecret };
+      return cache;
+    }
+    cache = null;
+    return null;
+  } catch {
+    cache = null;
+    return null;
+  }
+}
+
+/** 키를 해시해서 저장(첫 실행 셋업). 새 cookieSecret 을 발급. 평문 키/시크릿은 로그 금지. */
+export function storeKey(key: string): StoredAuth {
+  const salt = randomBytes(16).toString('hex');
+  const hash = scryptHex(key, salt);
+  const cookieSecret = randomBytes(32).toString('hex');
+  const rec: StoredAuth = { algo: 'scrypt', salt, hash, cookieSecret };
+  fs.mkdirSync(path.dirname(AUTH_PATH), { recursive: true });
+  fs.writeFileSync(AUTH_PATH, JSON.stringify(rec), { mode: 0o600 });
+  try { fs.chmodSync(AUTH_PATH, 0o600); } catch { /* best effort */ }
+  cache = rec;
+  return rec;
+}
+
+/** 저장된 키 파일 삭제(reset-key). 다음 부팅은 다시 첫 실행 셋업. */
+export function clearStored(): boolean {
+  cache = undefined;
+  try {
+    if (fs.existsSync(AUTH_PATH)) { fs.rmSync(AUTH_PATH); return true; }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function authFilePath(): string { return AUTH_PATH; }
+
+// ── precedence 결정 ────────────────────────────────────────────────
+// 1) COXPIT_AUTH_DISABLED=1 → off  2) env COXPIT_AUTH_PASS → env-mode
+// 3) auth.json 존재 → stored  4) 아무것도 없음 → 첫 실행 셋업
+export type AuthMode =
+  | { mode: 'disabled' }
+  | { mode: 'env'; key: string }
+  | { mode: 'stored'; rec: StoredAuth }
+  | { mode: 'setup' };
+
+/**
+ * 데몬이 외부에 노출된 바인드인가 — loopback-only(127.0.0.1/::1/localhost)면 로컬 신뢰(false),
+ * 0.0.0.0 이나 라우팅 가능한 IP 면 노출(true). 노출일 때만 접근키 인증을 적용한다.
+ * (npx coxpit 로컬 = 무마찰; 레지던트 COXPIT_HOST=0.0.0.0 = 키 필요.)
+ */
+export function isExposedBind(): boolean {
+  const host = (config.host ?? '').trim().toLowerCase();
+  if (host === '' || host === '127.0.0.1' || host === '::1' || host === 'localhost' || host === '::ffff:127.0.0.1') {
+    return false;
+  }
+  return true;
+}
+
+export function authMode(): AuthMode {
+  if (config.auth.disabled) return { mode: 'disabled' };
+  // loopback-only 바인드 = 로컬 신뢰 → 인증 없음(login/setup 페이지도 없음).
+  if (!isExposedBind()) return { mode: 'disabled' };
+  if (config.auth.pass !== '') return { mode: 'env', key: config.auth.pass };
+  const rec = loadStored();
+  if (rec) return { mode: 'stored', rec };
+  return { mode: 'setup' };
+}
+
+/** 인증이 실질적으로 열려있나(비번 없음) — Funnel 가드·authOpen 배지용. */
+export function authIsOpen(): boolean {
+  const m = authMode();
+  return m.mode === 'disabled' || m.mode === 'setup';
+}
+
+/** 주어진 키가 현재 구성된 키와 일치하나(상수시간). env/stored 양쪽. */
+export function verifyKey(key: string, m: AuthMode = authMode()): boolean {
+  if (m.mode === 'env') {
+    // env 는 평문 비교지만 상수시간으로 — 같은 salt 로 양쪽 해시 후 비교.
+    const salt = 'coxpit-env-mode-fixed-salt';
+    return constantEqHex(scryptHex(key, Buffer.from(salt).toString('hex')), scryptHex(m.key, Buffer.from(salt).toString('hex')));
+  }
+  if (m.mode === 'stored') {
+    return constantEqHex(scryptHex(key, m.rec.salt), m.rec.hash);
+  }
+  return false;
+}
+
+/** 쿠키 서명 시크릿 — stored 면 cookieSecret, env 면 그 키에서 파생(무상태). */
+function cookieSecretFor(m: AuthMode = authMode()): string {
+  if (m.mode === 'stored') return m.rec.cookieSecret;
+  if (m.mode === 'env') return scryptHex(m.key, Buffer.from('coxpit-cookie-derive').toString('hex'));
+  return '';
+}
+
+export const SESSION_COOKIE = 'coxpit_sess';
+
+// 쿠키 값 = "<expiryMs>.<hmac>" — 서버 세션 스토어 없이 stateless 검증.
+// expiry=0 → 세션 쿠키(무만료 스탬프, 브라우저 종료 시 소멸)지만 서명은 항상 검증.
+export function signSession(expiryMs: number, m: AuthMode = authMode()): string {
+  const secret = cookieSecretFor(m);
+  const stamp = String(expiryMs);
+  const mac = createHmac('sha256', secret).update(stamp).digest('hex');
+  return stamp + '.' + mac;
+}
+
+export function verifySession(value: string, m: AuthMode = authMode()): boolean {
+  const secret = cookieSecretFor(m);
+  if (!secret) return false;
+  const dot = value.lastIndexOf('.');
+  if (dot <= 0) return false;
+  const stamp = value.slice(0, dot);
+  const mac = value.slice(dot + 1);
+  const expiry = Number(stamp);
+  if (!Number.isFinite(expiry)) return false;
+  const want = createHmac('sha256', secret).update(stamp).digest('hex');
+  if (!constantEqHex(mac, want)) return false;
+  if (expiry !== 0 && Date.now() > expiry) return false; // 만료
+  return true;
+}
+
+/** 요청 헤더에서 쿠키 하나 파싱(라이브러리 없이 최소 수동). */
+export function readCookie(cookieHeader: string | undefined, name: string): string | null {
+  if (!cookieHeader) return null;
+  for (const part of cookieHeader.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    const k = part.slice(0, eq).trim();
+    if (k === name) return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return null;
+}
+
+// ── 레이트리밋(per-client, in-memory, 백오프) ───────────────────────
+interface Bucket { fails: number; blockedUntil: number }
+const buckets = new Map<string, Bucket>();
+const FREE_ATTEMPTS = 5;
+// 5회 초과부터 창이 커진다: 5s → 30s → 2m → 5m(상한)
+const BACKOFF_MS = [5_000, 30_000, 120_000, 300_000];
+
+export function clientKey(headers: Record<string, unknown>, socketIp: string): string {
+  const h = (k: string): string => {
+    const v = headers[k];
+    if (Array.isArray(v)) return String(v[0] ?? '');
+    return typeof v === 'string' ? v : '';
+  };
+  const fwd = h('x-forwarded-for').split(',')[0]!.trim();
+  return h('cf-connecting-ip') || fwd || socketIp || 'unknown';
+}
+
+/** 지금 시도해도 되나. 막혀있으면 { blocked:true, retryMs }. */
+export function rateCheck(id: string): { blocked: boolean; retryMs: number; attemptsLeft: number } {
+  const b = buckets.get(id);
+  const now = Date.now();
+  if (b && b.blockedUntil > now) {
+    return { blocked: true, retryMs: b.blockedUntil - now, attemptsLeft: 0 };
+  }
+  const fails = b ? b.fails : 0;
+  return { blocked: false, retryMs: 0, attemptsLeft: Math.max(0, FREE_ATTEMPTS - fails) };
+}
+
+/** 실패 1건 기록 → 필요 시 블록 창 설정. 반환은 이후 상태(다음 시도 안내용). */
+export function rateFail(id: string): { retryMs: number; attemptsLeft: number } {
+  const now = Date.now();
+  const b = buckets.get(id) ?? { fails: 0, blockedUntil: 0 };
+  b.fails += 1;
+  if (b.fails > FREE_ATTEMPTS) {
+    const over = b.fails - FREE_ATTEMPTS - 1;
+    const win = BACKOFF_MS[Math.min(over, BACKOFF_MS.length - 1)]!;
+    b.blockedUntil = now + win;
+  }
+  buckets.set(id, b);
+  const blockedFor = b.blockedUntil > now ? b.blockedUntil - now : 0;
+  return { retryMs: blockedFor, attemptsLeft: Math.max(0, FREE_ATTEMPTS - b.fails) };
+}
+
+/** 성공 시 리셋. */
+export function rateReset(id: string): void { buckets.delete(id); }
+
+// ── 첫 실행 셋업 토큰(Jupyter 스타일) ──────────────────────────────
+// 부팅 시 키가 없으면 1회용 토큰을 stdout(=로그)에 찍는다. 로그 접근 = 머신 소유.
+let setupToken: string | null = null;
+
+export function ensureSetupToken(): string {
+  if (!setupToken) setupToken = randomBytes(24).toString('hex');
+  return setupToken;
+}
+
+export function getSetupToken(): string | null { return setupToken; }
+
+export function verifySetupToken(token: string): boolean {
+  if (!setupToken || !token) return false;
+  return constantEqHex(Buffer.from(token).toString('hex'), Buffer.from(setupToken).toString('hex'));
+}
+
+/**
+ * 셋업 anti-claim — 이 요청이 증명 가능한 소유자인가.
+ * (A) 셋업 토큰 일치(로그 접근자), 또는
+ * (B) 진짜 로컬: 소켓 remote 가 loopback AND forwarding 헤더 부재.
+ * 터널을 탄 요청(127.0.0.1 이지만 cf/x-forwarded 헤더 보유)은 (A) 토큰 필수.
+ */
+export function isLoopback(ip: string): boolean {
+  return ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1' || ip === 'localhost';
+}
+
+export function setupAllowed(
+  headers: Record<string, unknown>,
+  remoteIp: string,
+  token: string,
+): { ok: boolean; via: 'token' | 'local' | null } {
+  if (verifySetupToken(token)) return { ok: true, via: 'token' };
+  const hasFwd = headers['x-forwarded-for'] != null || headers['cf-connecting-ip'] != null;
+  if (isLoopback(remoteIp) && !hasFwd) return { ok: true, via: 'local' };
+  return { ok: false, via: null };
+}