coxpit 4.7.0 → 4.8.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": "4.8.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 };
+}

package/src/board.ts

@@ -1,5 +1,7 @@
 // 데몬이 서빙하는 단일 페이지 플릿 콘솔(빌드 스텝 0, 자가완결).
 // /api/fleet 로 하이드레이트 → /ws 구독 델타 → run 상세(타임라인·diff·터미널)·비교/머지.
+import { ICON_SPRITE, ICON_CSS, ICON_JS_HELPER } from './icons.js';
+
 export const BOARD_HTML = /* html */ `<!doctype html>
 <html lang="en">
 <head>
@@ -400,7 +402,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
   .rmt-tbl th{color:var(--faint);font-family:var(--mono);font-size:10px;text-transform:uppercase;letter-spacing:.1em}
   .rmt-tbl code{font-family:var(--mono);font-size:10.5px;color:var(--brand);white-space:nowrap}
   .rmt-tbl .star{color:var(--brand)}
-  /* header 🔗 affordance shares the ghost-button look */
+  /* header remote-access affordance shares the ghost-button look */
 
   /* ── toasts ─────────────────────────────── */
   .toasts{position:fixed;top:66px;right:18px;z-index:60;display:flex;flex-direction:column;gap:8px;
@@ -529,6 +531,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
   .ocard.miss{opacity:.72;border-style:dashed;cursor:default}
   .ocard.miss:hover{transform:none;border-color:var(--line)}
   .ocard .og{font-size:15px;line-height:1;flex:0 0 auto;width:20px;text-align:center;color:var(--muted)}
+  .ocard.miss .og{color:var(--s-preparing)}
   .ocard .ob{flex:1;min-width:0;display:flex;flex-direction:column;gap:2px}
   .ocard .ot{font-family:var(--sans);font-size:12.5px;color:var(--ink);font-weight:600;
     white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
@@ -603,9 +606,11 @@ export const BOARD_HTML = /* html */ `<!doctype html>
     .cmp-col{min-width:0;border-right:none;border-bottom:1px solid var(--line);flex:0 0 auto;max-height:72vh}
   }
   @media (prefers-reduced-motion:reduce){aside{transition:none}}
+  ${ICON_CSS}
 </style>
 </head>
 <body>
+${ICON_SPRITE}
 <header>
   <button class="btn-ghost sm menu-btn" id="menuBtn" aria-label="open launcher">☰</button>
   <div class="brand"><span class="mark">coxpit</span><span class="sub">fleet console</span></div>
@@ -615,8 +620,8 @@ export const BOARD_HTML = /* html */ `<!doctype html>
     <button type="button" class="seg-opt" data-view="archive">Archive <span id="archN" class="seg-hint"></span></button>
   </div>
   <div class="ws"><span class="dot" id="wsdot"></span><span id="wstext">connecting</span></div>
-  <button class="btn-ghost sm" id="bell" title="notify when a run settles">🔕</button>
-  <button class="btn-ghost sm" id="remoteBtn" title="reach this daemon from elsewhere (Tailscale · recipes)">🔗</button>
+  <button class="btn-ghost sm" id="bell" title="notify when a run settles"><svg class="ic"><use href="#i-bell-off"/></svg></button>
+  <button class="btn-ghost sm" id="remoteBtn" title="reach this daemon from elsewhere (Tailscale · recipes)"><svg class="ic"><use href="#i-external-link"/></svg></button>
   <div class="machines" id="machines"></div>
 </header>
 <div class="scrim" id="scrim"></div>
@@ -632,8 +637,8 @@ export const BOARD_HTML = /* html */ `<!doctype html>
         <button type="button" class="btn-ghost sm" id="repoBrowse" style="flex:1">Browse…</button>
         <button type="button" class="btn-ghost sm" id="repoNew" style="flex:0 0 auto" title="start a new project — empty folder in, scaffolded repo out">New</button>
         <button type="button" class="btn-ghost sm" id="repoManual" style="flex:0 0 auto" title="type an absolute path">Path</button>
-        <button type="button" class="btn-ghost sm" id="repoBranch" style="flex:0 0 auto" title="change the base branch — merges, Sync base and PRs all target it">⎇</button>
-        <button type="button" class="btn-ghost sm" id="repoRemove" style="flex:0 0 auto" title="remove selected repository from coxpit">×</button>
+        <button type="button" class="btn-ghost sm" id="repoBranch" style="flex:0 0 auto" title="change the base branch — merges, Sync base and PRs all target it"><svg class="ic"><use href="#i-branch"/></svg></button>
+        <button type="button" class="btn-ghost sm" id="repoRemove" style="flex:0 0 auto" title="remove selected repository from coxpit"><svg class="ic"><use href="#i-x"/></svg></button>
       </div>
       <form id="repoForm" hidden>
         <div class="row">
@@ -687,7 +692,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
         <input type="checkbox" id="taskReal" hidden />
         <div class="row">
           <input id="taskCount" class="narrow" type="number" min="1" max="8" value="1" title="agents — 1 for a job, N to explore variants" />
-          <button class="btn" type="submit" id="runFleetBtn">Run fleet</button>
+          <button class="btn" type="submit" id="runFleetBtn"><svg class="ic"><use href="#i-play"/></svg> Run fleet</button>
         </div>
       </form>
     </div>
@@ -714,7 +719,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
         <input id="archQ" placeholder="search title…" autocomplete="off" />
         <select id="archRepo"><option value="">all repos</option></select>
         <button type="button" class="btn-ghost sm" id="reclaimBtn" hidden
-          title="remove worktrees left by cleaned/failed runs — reclaims disk (active work untouched)">♻ Reclaim <span id="reclaimHint"></span></button>
+          title="remove worktrees left by cleaned/failed runs — reclaims disk (active work untouched)"><svg class="ic"><use href="#i-recycle"/></svg> Reclaim <span id="reclaimHint"></span></button>
       </div>
       <div id="archList"></div>
       <div style="text-align:center;margin-top:14px"><button class="btn-ghost sm" id="archMore" hidden>load 50 more</button></div>
@@ -728,7 +733,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <span class="rid" id="mRid"></span>
       <span class="title" id="mTitle"></span>
       <span class="chip" id="mChip"><i></i><span id="mChipTxt"></span></span>
-      <button class="x" id="mClose" aria-label="close">×</button>
+      <button class="x" id="mClose" aria-label="close"><svg class="ic"><use href="#i-x"/></svg></button>
     </div>
     <div class="contract" id="mContract" hidden></div>
     <div class="modal-b">
@@ -753,14 +758,14 @@ export const BOARD_HTML = /* html */ `<!doctype html>
         <button type="button" class="seg-opt" data-mode="ask">Ask</button>
       </div>
       <input id="steerInput" placeholder="Next instruction — same session &amp; worktree…" style="flex:1" />
-      <button class="btn sm" id="steerSend">Send</button>
+      <button class="btn sm" id="steerSend"><svg class="ic"><use href="#i-pencil"/></svg> Send</button>
     </div>
     <div class="modal-f">
-      <button class="btn-ghost sm" id="mTerm">Terminal</button>
-      <button class="btn-ghost sm" id="mRefreshDiff">Refresh outputs</button>
+      <button class="btn-ghost sm" id="mTerm"><svg class="ic"><use href="#i-terminal"/></svg> Terminal</button>
+      <button class="btn-ghost sm" id="mRefreshDiff"><svg class="ic"><use href="#i-refresh"/></svg> Refresh outputs</button>
       <button class="btn-ghost sm" id="mCompare">Compare runs</button>
-      <button class="btn-ghost sm" id="mExport">Export files…</button>
-      <button class="btn-ghost sm" id="mSync">Sync base</button>
+      <button class="btn-ghost sm" id="mExport"><svg class="ic"><use href="#i-download"/></svg> Export files…</button>
+      <button class="btn-ghost sm" id="mSync"><svg class="ic"><use href="#i-branch"/></svg> Sync base</button>
       <button class="btn-ghost sm" id="mShare" title="create a read-only share link (no auth, snapshot view)">Share</button>
       <span class="spacer"></span>
       <button class="btn-danger sm" id="mStop">Stop</button>
@@ -776,7 +781,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <span class="rh-glyph">⌒</span>
       <span class="rh-t" id="roomTitle">Goal</span>
       <span class="rh-n" id="roomCount"></span>
-      <button class="x" id="roomClose" aria-label="close">×</button>
+      <button class="x" id="roomClose" aria-label="close"><svg class="ic"><use href="#i-x"/></svg></button>
     </div>
     <div class="chips" id="roomChips"></div>
     <div class="gbar" id="roomGbar">
@@ -798,7 +803,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <div class="comp-hint" id="roomHint"></div>
       <textarea id="roomInput" placeholder="New attempt prompt, or a broadcast to the settled runs…"></textarea>
       <div class="verbs" id="roomVerbs">
-        <button type="button" class="btn-ghost sm" id="roomNew">＋ New attempt</button>
+        <button type="button" class="btn-ghost sm" id="roomNew"><svg class="ic"><use href="#i-plus"/></svg> New attempt</button>
         <button type="button" class="btn-ghost sm" id="roomBroadcast">→ Broadcast</button>
         <span class="grow"></span>
         <div class="conv-menu" id="roomConvMenu">
@@ -824,7 +829,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <button class="btn sm" id="cmpAI">AI review</button>
       <button class="btn-ghost sm" id="cmpDocsTgl">Rendered</button>
       <button class="btn-ghost sm" id="cmpRefresh">Refresh</button>
-      <button class="x" id="cmpClose" aria-label="close">×</button>
+      <button class="x" id="cmpClose" aria-label="close"><svg class="ic"><use href="#i-x"/></svg></button>
     </div>
     <div class="cmp-review" id="cmpReview" hidden></div>
     <div class="cmp" id="cmpBody"></div>
@@ -838,7 +843,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <span class="title" id="termTitle">terminal</span>
       <div class="term-tabs" id="termTabs"></div>
       <span class="term-hint">tmux session · Ctrl-b d detaches · Esc closes</span>
-      <button class="x" id="termClose" aria-label="close">×</button>
+      <button class="x" id="termClose" aria-label="close"><svg class="ic"><use href="#i-x"/></svg></button>
     </div>
     <div class="term-body"><div id="xterm"></div></div>
     <div class="term-ibar" id="termIbar">
@@ -860,12 +865,12 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <button class="btn-ghost sm" id="brwUp">↑ Up</button>
       <button class="btn-ghost sm" id="brwHome">Home</button>
       <span class="brw-path" id="brwPath"></span>
-      <button class="x" id="brwClose" aria-label="close">×</button>
+      <button class="x" id="brwClose" aria-label="close"><svg class="ic"><use href="#i-x"/></svg></button>
     </div>
     <div class="brw-list" id="brwList"></div>
     <div class="brw-f">
       <span class="hint"><span style="color:var(--brand)">git</span> badge = repo (Register) · empty folder = Start here</span>
-      <button class="btn-ghost sm" id="brwNewFolder">＋ New folder here</button>
+      <button class="btn-ghost sm" id="brwNewFolder"><svg class="ic"><use href="#i-plus"/></svg> New folder here</button>
       <button class="btn sm" id="brwRegHere" style="display:none">Register this folder</button>
     </div>
     <form class="brw-f" id="brwNewForm" hidden>
@@ -983,13 +988,14 @@ let remoteAuthOpen = false; // true = no password → Funnel guard on (from /api
 const $ = (id) => document.getElementById(id);
 const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
 const escA = (s) => esc(s).replace(/"/g, '&quot;');
+${ICON_JS_HELPER}   // ic('x') → '<svg class="ic"><use href="#i-x"/></svg>' (Lucide 스프라이트)
 const statusColor = (s) => 'var(--s-' + (s||'pending') + ', var(--muted))';
 
 /* ── custom toast / confirm (시스템 alert·confirm 대체) ── */
 function toast(msg, kind){
   const el = document.createElement('div');
   el.className = 'toast ' + (kind==='error'?'err':kind==='ok'?'ok':'');
-  el.innerHTML = '<span class="tk">'+(kind==='error'?'✕':kind==='ok'?'✓':'·')+'</span><span>'+esc(msg)+'</span>';
+  el.innerHTML = '<span class="tk">'+(kind==='error'?ic('x'):kind==='ok'?ic('check'):'·')+'</span><span>'+esc(msg)+'</span>';
   $('toasts').appendChild(el);
   setTimeout(()=>{ el.style.opacity='0'; el.style.transition='opacity .25s'; setTimeout(()=>el.remove(),260); }, 4200);
 }
@@ -1041,7 +1047,7 @@ async function brwGo(p){
   $('brwList').innerHTML =
     (d.error ? '<div class="brw-row"><span class="nm" style="color:var(--s-failed)">'+esc(d.error)+'</span></div>' : '')
     + (d.dirs.map(x =>
-        '<div class="brw-row" data-n="'+esc(x.name)+'"><span class="ico">▸</span><span class="nm">'+esc(x.name)+'</span>'
+        '<div class="brw-row" data-n="'+esc(x.name)+'"><span class="ico">'+ic('folder')+'</span><span class="nm">'+esc(x.name)+'</span>'
         + (x.isRepo ? '<span class="gitchip">git</span><button type="button" class="btn sm" data-reg="'+esc(x.name)+'">Register</button>'
            : x.isEmpty ? '<button type="button" class="btn-ghost sm" data-start="'+esc(x.name)+'">Start here</button>' : '')
         + '</div>').join('')
@@ -1375,7 +1381,7 @@ async function probeFirstMachine(){
 }
 function chkRow(name, ok, val){
   const cls = ok===null ? 'wait' : ok ? 'ok' : 'bad';
-  const st = ok===null ? '…' : ok ? '✓' : '✕';
+  const st = ok===null ? '…' : ok ? ic('check') : ic('x');
   return '<div class="chk '+cls+'"><span class="st">'+st+'</span><span class="nm">'+esc(name)+'</span>'
     + '<span class="v">'+esc(val||'')+'</span></div>';
 }
@@ -1423,7 +1429,7 @@ function cardHTML(r){
   const selCls = (selectMode?' selmode':'') + (selected.has(r.id)?' selected':'') + (closed?' closed':'');
   return '<div class="card'+selCls+'" id="card-'+r.id+'">'
     + '<div class="card-h"><span class="rid">r'+r.id+'</span><span class="title">'+title+'</span>'
-    + '<span class="selbox">✓</span>'+chipHTML(r.status)+'</div>'
+    + '<span class="selbox">'+ic('check')+'</span>'+chipHTML(r.status)+'</div>'
     + '<div class="meta"><span>branch <b>'+esc(r.branch||'—')+'</b></span>'
     + '<span>files <b>'+(r.filesChanged??0)+'</b></span>'
     + '<span>'+esc(r.agent||'')+'</span>'
@@ -1432,7 +1438,7 @@ function cardHTML(r){
     + (task && task.parentRunId ? '<span title="spawned by agent r'+task.parentRunId+'">↳ by r'+task.parentRunId+'</span>' : '')
     + (r.sessionId && ['done','failed','stopped'].includes(r.status)
         ? '<span class="resumable" title="agent session preserved — open the run and Send a next instruction to continue">↻ resumable</span>' : '')
-    + (r.prUrl ? '<a href="'+esc(r.prUrl)+'" target="_blank" rel="noopener" style="margin-left:auto">PR ↗</a>' : '')
+    + (r.prUrl ? '<a href="'+esc(r.prUrl)+'" target="_blank" rel="noopener" style="margin-left:auto">PR '+ic('external-link')+'</a>' : '')
     + '</div>'
     + '<div class="log">'+evs+'</div></div>';
 }
@@ -1535,7 +1541,7 @@ $('repoManual').addEventListener('click', ()=>{
 /* ── 완료 알림(브라우저) — 벨 토글, run 정착 시 통지 ── */
 let notifyOn = false;
 try { notifyOn = localStorage.getItem('coxpit.notify') === '1' && Notification.permission === 'granted'; } catch {}
-function paintBell(){ $('bell').textContent = notifyOn ? '🔔' : '🔕'; }
+function paintBell(){ $('bell').innerHTML = ic(notifyOn ? 'bell' : 'bell-off'); }
 $('bell').addEventListener('click', async ()=>{
   if (!('Notification' in window)){ toast('this browser has no notification support', 'error'); return; }
   if (!notifyOn){
@@ -1634,7 +1640,7 @@ function paintModal(){
    /outputs 로 카드 목록을 받아 렌더하고, 클릭하면 타입별 실뷰어를 오른쪽에 띄운다.
    answer/doc → mdLite · page → sandbox iframe · code → 기존 diff 렌더러 · file → 이미지/다운로드. */
 let outCards = [];                 // 이 run 의 마지막 카드 목록(RunOutputCard[])
-const OUT_GLYPH = { answer:'✦', code:'‹›', doc:'▤', page:'◱', file:'⎘' };
+const OUT_ICON = { answer:'message', code:'code', doc:'file', page:'image', file:'image' };
 const OUT_LABEL = { answer:'답변', code:'코드', doc:'문서', page:'페이지', file:'파일' };
 function contractHTML(cards){
   const declared = cards.filter(c=>c.required);
@@ -1644,7 +1650,7 @@ function contractHTML(cards){
   if (declared.length){
     h += declared.map(c=>{
       const ok = c.present;
-      return '<span class="req '+(ok?'ok':'warn')+'"><span class="rg">'+(ok?'✓':'!')+'</span>'
+      return '<span class="req '+(ok?'ok':'warn')+'"><span class="rg">'+ic(ok?'check':'alert-triangle')+'</span>'
         + esc(OUT_LABEL[c.type]||c.type)+'</span>';
     }).join('');
   } else h += '<span class="req aux">없음</span>';
@@ -1659,14 +1665,14 @@ function outCardHTML(c, i){
   const badge = c.required
     ? '<span class="obadge '+(c.present?'req':'warn')+'">요청됨</span>'
     : '<span class="obadge">부수</span>';
-  const glyph = OUT_GLYPH[c.type] || '•';
+  const gname = miss ? 'alert-triangle' : (OUT_ICON[c.type] || 'circle');
   const meta = miss ? '산출물 미충족 — '+esc(c.meta||'') : esc(c.meta||'');
   return '<div class="ocard'+(miss?' miss':'')+'" data-oi="'+i+'">'
-    + '<span class="og">'+esc(glyph)+'</span>'
+    + '<span class="og">'+ic(gname)+'</span>'
     + '<span class="ob"><span class="ot">'+esc(c.title||c.type)+'</span>'
     + '<span class="om">'+meta+'</span></span>'
     + badge
-    + (miss?'':'<span class="oc">›</span>')
+    + (miss?'':'<span class="oc">'+ic('chevron')+'</span>')
     + '</div>';
 }
 /* run 형태로 기본 카드 선택 — 코드 변경 없고 answer/doc 있으면 그걸, 코드 위주면 code,
@@ -2021,7 +2027,7 @@ async function paintCompare(){
       + '<div class="cmp-meta" title="'+esc(summary)+'">'+(summary?esc(summary):'—')+'</div>'
       + '<div class="cmp-diff"><pre class="diff">'+diffHTML(r.diff||'')+'</pre></div>'
       + '<div class="cmp-f"><span class="msg" id="cmpMsg-'+r.id+'">'
-      + (r.prUrl ? '<a href="'+esc(r.prUrl)+'" target="_blank" rel="noopener">PR ↗ '+esc(r.prUrl.split('/').slice(-1)[0])+'</a>' : '')
+      + (r.prUrl ? '<a href="'+esc(r.prUrl)+'" target="_blank" rel="noopener">PR '+ic('external-link')+' '+esc(r.prUrl.split('/').slice(-1)[0])+'</a>' : '')
       + '</span>'
       + (merged
         ? chipHTML('merged')
@@ -2157,7 +2163,7 @@ function roomRunRowHTML(r){
     : (running ? '<span class="run-badge running">running</span>' : '');
   // running·merged 는 체크박스로 선택 불가(정착·미머지만 Integrate 대상)
   const selectable = !merged && !running && (r.filesChanged||0)>0;
-  const cb = '<span class="cb" data-rcb="'+(selectable?r.runId:'')+'"'+(selectable?'':' style="opacity:.4;cursor:default"')+'>'+(sel?'✓':'')+'</span>';
+  const cb = '<span class="cb" data-rcb="'+(selectable?r.runId:'')+'"'+(selectable?'':' style="opacity:.4;cursor:default"')+'>'+(sel?ic('check'):'')+'</span>';
   return '<div class="run'+(sel?' sel':'')+(merged?' dim':'')+(open?' open':'')+'" data-rrun="'+r.runId+'">'
     + '<div class="run-h">'+cb
     + '<span class="dot '+dotCls+'"></span>'
@@ -2335,7 +2341,7 @@ $('roomRuns').addEventListener('click', async (e)=>{
     e.stopPropagation();
     const id = Number(cb.dataset.rcb); if (!id) return;
     if (roomSel.has(id)) roomSel.delete(id); else roomSel.add(id);
-    cb.textContent = roomSel.has(id) ? '✓' : '';
+    cb.innerHTML = roomSel.has(id) ? ic('check') : '';
     cb.closest('.run').classList.toggle('sel', roomSel.has(id));
     roomUpdateGbar();
     return;
@@ -2410,7 +2416,7 @@ async function roomRunAction(act, rid){
     return;
   }
 }
-/* [리뷰] — 그 run 의 태스크에 reviewTask(/tasks/:id/review) 를 돌려 ◆ 요약을 행 안에 인라인 표시. */
+/* [리뷰] — 그 run 의 태스크에 reviewTask(/tasks/:id/review) 를 돌려 요약을 행 안에 인라인 표시. */
 async function reviewOneRun(r){
   const row = document.querySelector('.run[data-rrun="'+r.runId+'"]'); if(!row) return;
   if (!roomOpen.has(r.runId)){ roomOpen.add(r.runId); row.classList.add('open'); roomLoadRunOutputs(r.runId); }
@@ -2418,14 +2424,14 @@ async function reviewOneRun(r){
   let rv = body.querySelector('.review.airev');
   if (!rv){ rv = document.createElement('div'); rv.className='review airev'; body.insertBefore(rv, body.querySelector('.fix')||null); }
   const real = $('taskReal').checked;
-  rv.innerHTML = '<span class="rk">◆ 리뷰</span><span class="rt">reviewing… ('+(real?'real':'dry')+')</span>';
+  rv.innerHTML = '<span class="rk">'+ic('message')+' 리뷰</span><span class="rt">reviewing… ('+(real?'real':'dry')+')</span>';
   try{
     const res = await fetch('/api/tasks/'+r.taskId+'/review',{method:'POST',
       headers:{'content-type':'application/json'}, body:JSON.stringify({real})});
     const j = await res.json().catch(()=>({}));
-    if (res.ok){ rv.innerHTML = '<span class="rk">◆ 리뷰</span><span class="rt">'+mdLite(j.review||'(no summary)')+'</span>'; }
-    else { rv.innerHTML = '<span class="rk">◆ 리뷰</span><span class="rt">review 실패 — '+esc(j.detail||String(res.status))+'</span>'; toast('review: '+(j.detail||res.status), 'error'); }
-  }catch{ rv.innerHTML = '<span class="rk">◆ 리뷰</span><span class="rt">review 요청 실패</span>'; }
+    if (res.ok){ rv.innerHTML = '<span class="rk">'+ic('message')+' 리뷰</span><span class="rt">'+mdLite(j.review||'(no summary)')+'</span>'; }
+    else { rv.innerHTML = '<span class="rk">'+ic('message')+' 리뷰</span><span class="rt">review 실패 — '+esc(j.detail||String(res.status))+'</span>'; toast('review: '+(j.detail||res.status), 'error'); }
+  }catch{ rv.innerHTML = '<span class="rk">'+ic('message')+' 리뷰</span><span class="rt">review 요청 실패</span>'; }
 }
 /* steer 입력 Enter → 전송 */
 $('roomRuns').addEventListener('keydown', (e)=>{

package/src/icons.ts

@@ -0,0 +1,42 @@
+// Lucide 아이콘 스프라이트(ISC 라이선스 · CDN 0 · 인라인). currentColor 상속.
+// board.ts / login.ts 가 공유한다. 경로는 전부 진짜 Lucide SVG(licenses/lucide.txt).
+// 사용: 정적 <svg class="ic"><use href="#i-…"/></svg> · 클라이언트 동적은 ic('name') 헬퍼.
+
+/** 숨김 <symbol> 스프라이트. <body> 최상단에 1벌 인라인. */
+export const ICON_SPRITE = `<svg style="position:absolute;width:0;height:0" aria-hidden="true">
+  <symbol id="i-lock" viewBox="0 0 24 24"><rect width="18" height="11" x="3" y="11" rx="2" ry="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></symbol>
+  <symbol id="i-unlock" viewBox="0 0 24 24"><rect width="18" height="11" x="3" y="11" rx="2" ry="2"/><path d="M7 11V7a5 5 0 0 1 9.9-1"/></symbol>
+  <symbol id="i-terminal" viewBox="0 0 24 24"><path d="m4 17 6-6-6-6"/><path d="M12 19h8"/></symbol>
+  <symbol id="i-folder" viewBox="0 0 24 24"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/></symbol>
+  <symbol id="i-branch" viewBox="0 0 24 24"><line x1="6" x2="6" y1="3" y2="15"/><circle cx="18" cy="6" r="3"/><circle cx="6" cy="18" r="3"/><path d="M18 9a9 9 0 0 1-9 9"/></symbol>
+  <symbol id="i-merge" viewBox="0 0 24 24"><circle cx="18" cy="18" r="3"/><circle cx="6" cy="6" r="3"/><path d="M6 21V9a9 9 0 0 0 9 9"/></symbol>
+  <symbol id="i-play" viewBox="0 0 24 24"><polygon points="6 3 20 12 6 21 6 3"/></symbol>
+  <symbol id="i-check" viewBox="0 0 24 24"><path d="M20 6 9 17l-5-5"/></symbol>
+  <symbol id="i-x" viewBox="0 0 24 24"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></symbol>
+  <symbol id="i-refresh" viewBox="0 0 24 24"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M8 16H3v5"/></symbol>
+  <symbol id="i-file" viewBox="0 0 24 24"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M16 13H8"/><path d="M16 17H8"/><path d="M10 9H8"/></symbol>
+  <symbol id="i-code" viewBox="0 0 24 24"><path d="m16 18 6-6-6-6"/><path d="m8 6-6 6 6 6"/></symbol>
+  <symbol id="i-image" viewBox="0 0 24 24"><rect width="18" height="18" x="3" y="3" rx="2" ry="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.09-3.09a2 2 0 0 0-2.82 0L6 21"/></symbol>
+  <symbol id="i-message" viewBox="0 0 24 24"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></symbol>
+  <symbol id="i-chevron" viewBox="0 0 24 24"><path d="m9 18 6-6-6-6"/></symbol>
+  <symbol id="i-plus" viewBox="0 0 24 24"><path d="M5 12h14"/><path d="M12 5v14"/></symbol>
+  <symbol id="i-pencil" viewBox="0 0 24 24"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/></symbol>
+  <symbol id="i-trash" viewBox="0 0 24 24"><path d="M3 6h18"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></symbol>
+  <symbol id="i-recycle" viewBox="0 0 24 24"><path d="M7 19H4.815a1.83 1.83 0 0 1-1.57-.881 1.785 1.785 0 0 1-.004-1.784L7.196 9.5"/><path d="M11 19h8.203a1.83 1.83 0 0 0 1.556-.89 1.784 1.784 0 0 0 0-1.775l-1.226-2.12"/><path d="m14 16-3 3 3 3"/><path d="M8.293 13.596 4.875 9.5 1.5 13.5"/><path d="m9 12 3-3-3-3"/><path d="M13.5 3.5 17 9.5l-3.5 2"/></symbol>
+  <symbol id="i-settings" viewBox="0 0 24 24"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"/><circle cx="12" cy="12" r="3"/></symbol>
+  <symbol id="i-external-link" viewBox="0 0 24 24"><path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/></symbol>
+  <symbol id="i-eye" viewBox="0 0 24 24"><path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"/><circle cx="12" cy="12" r="3"/></symbol>
+  <symbol id="i-alert-triangle" viewBox="0 0 24 24"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></symbol>
+  <symbol id="i-bell" viewBox="0 0 24 24"><path d="M10.268 21a2 2 0 0 0 3.464 0"/><path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326"/></symbol>
+  <symbol id="i-bell-off" viewBox="0 0 24 24"><path d="M10.268 21a2 2 0 0 0 3.464 0"/><path d="M17 17H4a1 1 0 0 1-.74-1.673C4.59 13.956 6 12.499 6 8a6 6 0 0 1 .258-1.742"/><path d="m2 2 20 20"/><path d="M8.668 3.01A6 6 0 0 1 18 8c0 2.687.77 4.653 1.707 6.05"/></symbol>
+  <symbol id="i-download" viewBox="0 0 24 24"><path d="M12 15V3"/><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/></symbol>
+  <symbol id="i-circle" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/></symbol>
+</svg>`;
+
+/** .ic 아이콘 스타일(1em·currentColor 상속·stroke). board/login 공통. */
+export const ICON_CSS =
+  `.ic{width:1em;height:1em;stroke:currentColor;fill:none;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;vertical-align:-.125em;flex:none}`;
+
+// 클라이언트에서 동적 HTML 문자열을 만들 때 쓰는 헬퍼 소스(보드 스크립트에 그대로 삽입).
+// ic('x') => '<svg class="ic"><use href="#i-x"/></svg>'
+export const ICON_JS_HELPER = `function ic(n){ return '<svg class="ic"><use href="#i-'+n+'"/></svg>'; }`;

package/src/index.ts

@@ -1,4 +1,5 @@
 import { config } from './config';
+import { authMode, ensureSetupToken, isExposedBind } from './authkey';
 import { db, ensureSchema } from './db';
 import { machines } from './db/schema';
 import { acquireDaemonLock } from './lock';
@@ -40,10 +41,25 @@ try {
   throw e;
 }
 
-// 인증 켜졌는데 비번이 비면 fail-closed(전 요청 401) — 첫 실행자가 401 보고 당황하지 않게 명시.
-if (!config.auth.disabled && config.auth.pass === '') {
-  console.warn(
-    '[coxpit] auth is ON but COXPIT_AUTH_PASS is empty — every request will be rejected (401).\n' +
-    '[coxpit] Set COXPIT_AUTH_PASS to a password, or COXPIT_AUTH_DISABLED=1 for local dev.',
-  );
+// 접근키 인증 상태 안내. 첫 실행(키 미설정)이면 브랜디드 셋업 페이지 + 1회용 셋업 토큰을 찍는다.
+// (토큰 = Jupyter 스타일: 로그 접근자 = 머신 소유자. 터널/타넷/로컬 어디서 붙어도 이 토큰으로 셋업 가능.)
+{
+  const m = authMode();
+  if (m.mode === 'disabled') {
+    if (config.auth.disabled) {
+      console.warn('[coxpit] auth is DISABLED (COXPIT_AUTH_DISABLED=1) — every request is allowed. Front it with your own gateway if exposed.');
+    } else if (!isExposedBind()) {
+      console.log(`[coxpit] loopback-only bind (${config.host}) — trusted local, no login required. Bind to 0.0.0.0 to require an access key.`);
+    }
+  } else if (m.mode === 'setup') {
+    const token = ensureSetupToken();
+    console.log(
+      '[coxpit] no access key configured yet — open the board to set one (first-run setup).\n' +
+      `[coxpit] one-time setup token (needed unless you visit http://127.0.0.1:${config.port} directly): ${token}`,
+    );
+  } else if (m.mode === 'env') {
+    console.log('[coxpit] access-key auth ON (COXPIT_AUTH_PASS) — the branded unlock page asks for that key.');
+  } else {
+    console.log('[coxpit] access-key auth ON (stored key) — the branded unlock page asks for your key.');
+  }
 }

package/src/login.ts

@@ -0,0 +1,124 @@
+// 브랜디드 접근키 언락/셋업 페이지(단일 자가완결 HTML — 빌드 0, 보드 토큰 매치).
+// 브라우저 basic-auth 팝업을 대체한다. fetch 로 A2/A3 엔드포인트 POST → 성공 시 보드로 reload.
+// setup=true → 첫 실행(키 설정, confirm 필드+토큰 힌트), false → 언락(키 1개).
+import { ICON_SPRITE, ICON_CSS } from './icons.js';
+
+/** login/setup 페이지 HTML. setup 이면 셋업(키+확인), 아니면 언락. */
+export function loginPageHTML(setup: boolean): string {
+  const title = setup ? 'set an access key' : 'unlock';
+  return /* html */ `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+<title>coxpit · ${title}</title>
+<style>
+  :root{
+    --bg:#0b0d12; --surface:#12151c; --surface2:#171b24; --line:#222835; --line-hi:#2f3648;
+    --ink:#dee4ec; --muted:#8792a2; --faint:#5c6675;
+    --brand:#4ec9b0; --brand-ink:#062822; --brand-dim:rgba(78,201,176,.13);
+    --s-failed:#e25b67; --s-preparing:#d6a249;
+    --mono:ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,monospace;
+    --sans:-apple-system,BlinkMacSystemFont,'Segoe UI',system-ui,Roboto,sans-serif;
+    --r-card:10px; --r-ctl:8px; --shadow:0 8px 28px rgba(0,0,0,.35);
+  }
+  *{box-sizing:border-box}
+  [hidden]{display:none !important}
+  html,body{height:100%}
+  body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);font-size:14px;line-height:1.5;
+    -webkit-font-smoothing:antialiased;display:flex;align-items:center;justify-content:center;padding:24px}
+  ::selection{background:var(--brand-dim)}
+  .card{width:100%;max-width:380px;background:var(--surface);border:1px solid var(--line);
+    border-radius:var(--r-card);box-shadow:var(--shadow);padding:26px 24px 22px}
+  .mark{font-family:var(--mono);font-weight:700;color:var(--brand);font-size:17px;letter-spacing:.02em;
+    display:flex;align-items:center;gap:9px}
+  .glyph{font-size:18px;line-height:1}
+  h1{font-size:15px;font-weight:600;margin:16px 0 4px;color:var(--ink)}
+  .sub{color:var(--muted);font-size:12.5px;margin:0 0 18px;line-height:1.5}
+  .flabel{display:block;font-family:var(--mono);font-size:10px;text-transform:uppercase;letter-spacing:.12em;
+    color:var(--faint);margin:0 0 6px}
+  input[type=password]{width:100%;background:#0e1118;border:1px solid var(--line);border-radius:var(--r-ctl);
+    color:var(--ink);font-family:var(--mono);font-size:14px;padding:10px 12px;outline:none}
+  input[type=password]:focus{border-color:var(--brand)}
+  input::placeholder{color:var(--faint)}
+  .fld{margin-bottom:14px}
+  .row{display:flex;align-items:center;gap:8px;margin:2px 0 16px;color:var(--muted);font-size:12.5px;user-select:none;cursor:pointer}
+  .row input{accent-color:var(--brand);width:15px;height:15px}
+  .btn{width:100%;background:var(--brand);color:var(--brand-ink);border:0;border-radius:var(--r-ctl);
+    font-family:var(--sans);font-weight:600;font-size:14px;padding:11px;cursor:pointer;
+    display:flex;align-items:center;justify-content:center;gap:8px}
+  .btn:disabled{opacity:.55;cursor:default}
+  .err{color:var(--s-failed);font-size:12.5px;min-height:17px;margin:0 0 12px;font-family:var(--mono)}
+  .hint{background:var(--surface2);border:1px solid var(--line);border-radius:var(--r-ctl);
+    padding:9px 11px;color:var(--muted);font-size:11.5px;line-height:1.55;margin:0 0 16px}
+  .hint code{font-family:var(--mono);color:var(--brand);font-size:11px}
+  .ft{margin-top:18px;padding-top:14px;border-top:1px solid var(--line);text-align:center}
+  .ft a{color:var(--faint);text-decoration:none;font-size:11.5px}
+  .ft a:hover{color:var(--muted)}
+  ${ICON_CSS}
+  .mark .ic{width:18px;height:18px}
+  .btn .ic{width:16px;height:16px}
+</style>
+</head>
+<body>
+${ICON_SPRITE}
+  <form class="card" id="f" autocomplete="off">
+    <div class="mark"><svg class="ic"><use href="#i-lock"/></svg><span>coxpit</span></div>
+    <h1>${setup ? 'Protect this coxpit' : 'Unlock this coxpit'}</h1>
+    <p class="sub">${setup
+      ? 'Set an access key. You&#39;ll enter it once per device — no accounts, no username.'
+      : 'Enter your access key. One key, one owner — no username.'}</p>
+    ${setup ? `<div class="hint">To prove you own this machine, this first-time setup needs the one-time
+      <code>setup token</code> printed in the daemon log &mdash; unless you&#39;re on
+      <code>http://127.0.0.1</code> directly. Paste it below if asked.</div>` : ''}
+    <div class="err" id="err"></div>
+    ${setup ? `<div class="fld"><label class="flabel" for="tok">setup token (from the daemon log)</label>
+      <input id="tok" type="password" placeholder="paste if not on localhost" autocomplete="off"></div>` : ''}
+    <div class="fld"><label class="flabel" for="key">access key</label>
+      <input id="key" type="password" placeholder="&#8226;&#8226;&#8226;&#8226;&#8226;&#8226;&#8226;&#8226;" autocomplete="${setup ? 'new-password' : 'current-password'}" autofocus></div>
+    ${setup ? `<div class="fld"><label class="flabel" for="key2">confirm access key</label>
+      <input id="key2" type="password" placeholder="&#8226;&#8226;&#8226;&#8226;&#8226;&#8226;&#8226;&#8226;" autocomplete="new-password"></div>` : ''}
+    <label class="row"><input id="rem" type="checkbox"${setup ? ' checked' : ''}><span>Remember this device</span></label>
+    <button class="btn" id="go" type="submit"><svg class="ic"><use href="#i-${setup ? 'lock' : 'unlock'}"/></svg><span>${setup ? 'Set key &amp; enter' : 'Unlock'}</span></button>
+    <div class="ft"><a href="https://github.com/hanmariyang/coxpit-oss#remote-access" target="_blank" rel="noopener">Fronting with Cloudflare Access / Tailscale? &rarr;</a></div>
+  </form>
+<script>
+(function(){
+  var SETUP = ${setup ? 'true' : 'false'};
+  var f = document.getElementById('f');
+  var err = document.getElementById('err');
+  var go = document.getElementById('go');
+  function show(m){ err.textContent = m || ''; }
+  f.addEventListener('submit', function(ev){
+    ev.preventDefault();
+    show('');
+    var key = document.getElementById('key').value;
+    var rem = document.getElementById('rem').checked;
+    if (!key){ show('access key required'); return; }
+    var body, url;
+    if (SETUP){
+      var key2 = document.getElementById('key2').value;
+      if (key !== key2){ show('keys do not match'); return; }
+      if (key.length < 6){ show('use at least 6 characters'); return; }
+      url = '/api/auth/setup';
+      body = { key: key, token: document.getElementById('tok').value, remember: rem };
+    } else {
+      url = '/api/auth/unlock';
+      body = { key: key, remember: rem };
+    }
+    go.disabled = true;
+    fetch(url, { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify(body) })
+      .then(function(r){ return r.json().then(function(j){ return { s:r.status, j:j }; }); })
+      .then(function(res){
+        if (res.s >= 200 && res.s < 300 && res.j && res.j.ok){ location.replace('/'); return; }
+        go.disabled = false;
+        var m = (res.j && (res.j.detail || res.j.error)) || ('error ' + res.s);
+        show(m);
+      })
+      .catch(function(){ go.disabled = false; show('network error'); });
+  });
+})();
+</script>
+</body>
+</html>`;
+}

package/src/server.ts

@@ -4,10 +4,14 @@ import { homedir } from 'node:os';
 import { resolve as presolve, dirname as pdirname, join as pjoin, sep as psep } from 'node:path';
 import { createRequire } from 'node:module';
 import { randomBytes } from 'node:crypto';
-import Fastify, { type FastifyInstance } from 'fastify';
+import Fastify, { type FastifyInstance, type FastifyReply } from 'fastify';
 import websocket from '@fastify/websocket';
 import { eq, inArray, and, like, desc } from 'drizzle-orm';
 import { authGate } from './auth';
+import {
+  authMode, authIsOpen, verifyKey, storeKey, signSession, SESSION_COOKIE,
+  clientKey, rateCheck, rateFail, rateReset, setupAllowed,
+} from './authkey';
 import { config } from './config';
 import { db } from './db';
 import { machines, repos, tasks, agentRuns, agentEvents, designCaptures, shareLinks, taskGroups } from './db/schema';
@@ -180,9 +184,81 @@ export async function buildServer(): Promise<FastifyInstance> {
   // 무인증 헬스(외부 감시용)
   app.get('/api/health', async () => ({ ok: true, name: 'coxpit', version: config.version }));
 
-  // 플릿 보드(단일 페이지). 인증 게이트 적용됨.
+  // 플릿 보드(단일 페이지). 인증 게이트 적용됨(무인증 요청은 게이트가 login/setup 페이지로 응답).
   app.get('/', async (_req, reply) => reply.type('text/html').send(BOARD_HTML));
 
+  // ─── 접근키 인증(access-key) ────────────────────────────────────
+  // 요청이 tunnel/https 를 탔나 — Secure 쿠키 여부 결정용.
+  const isSecureReq = (req: { headers: Record<string, unknown> }): boolean => {
+    const proto = String(req.headers['x-forwarded-proto'] ?? '');
+    return proto.split(',')[0]!.trim() === 'https' || req.headers['cf-connecting-ip'] != null;
+  };
+  const REMEMBER_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+  // 세션 쿠키 헤더 조립(라이브러리 없이). remember → Max-Age 30d, else 세션 쿠키.
+  const setSessionCookie = (
+    reply: FastifyReply, req: { headers: Record<string, unknown> }, remember: boolean,
+  ): void => {
+    const expiry = remember ? Date.now() + REMEMBER_MS : 0;
+    const value = signSession(expiry);
+    const parts = [
+      `${SESSION_COOKIE}=${encodeURIComponent(value)}`,
+      'Path=/', 'HttpOnly', 'SameSite=Lax',
+    ];
+    if (remember) parts.push(`Max-Age=${Math.floor(REMEMBER_MS / 1000)}`);
+    if (isSecureReq(req)) parts.push('Secure');
+    reply.header('set-cookie', parts.join('; '));
+  };
+  const socketIp = (req: { socket?: { remoteAddress?: string } }): string =>
+    String(req.socket?.remoteAddress ?? '');
+
+  // 첫 실행 셋업(anti-claim) — 셋업 토큰 일치 OR 진짜 로컬(loopback+no-fwd)만 허용.
+  // 키가 이미 있으면 409(단발). 성공 시 해시 저장 + 세션 쿠키.
+  app.post('/api/auth/setup', async (req, reply) => {
+    if (authMode().mode !== 'setup') return reply.code(409).send({ error: 'already configured' });
+    const b = (req.body ?? {}) as { key?: string; token?: string; remember?: boolean };
+    const key = String(b.key ?? '');
+    if (key.length < 6) return reply.code(400).send({ error: 'key too short', detail: 'use at least 6 characters' });
+    const gate = setupAllowed(req.headers as Record<string, unknown>, socketIp(req), String(b.token ?? ''));
+    if (!gate.ok) {
+      return reply.code(403).send({ error: 'setup not allowed', detail: 'paste the one-time setup token from the daemon log (this request is not local)' });
+    }
+    storeKey(key); // 평문 키는 절대 로그하지 않음
+    setSessionCookie(reply, req, b.remember === true);
+    return reply.code(201).send({ ok: true });
+  });
+
+  // 언락 — 상수시간 검증 + per-client 레이트리밋(백오프). 성공 시 세션 쿠키.
+  app.post('/api/auth/unlock', async (req, reply) => {
+    const m = authMode();
+    if (m.mode === 'disabled') return reply.send({ ok: true });
+    if (m.mode === 'setup') return reply.code(409).send({ error: 'not configured', detail: 'set an access key first' });
+    const id = clientKey(req.headers as Record<string, unknown>, socketIp(req));
+    const rc = rateCheck(id);
+    if (rc.blocked) {
+      const secs = Math.ceil(rc.retryMs / 1000);
+      return reply.code(429).send({ error: 'too many attempts', detail: `try again in ${secs}s` });
+    }
+    const b = (req.body ?? {}) as { key?: string; remember?: boolean };
+    if (verifyKey(String(b.key ?? ''), m)) {
+      rateReset(id);
+      setSessionCookie(reply, req, b.remember === true);
+      return reply.send({ ok: true });
+    }
+    const after = rateFail(id);
+    const detail = after.retryMs > 0
+      ? `wrong key — try again in ${Math.ceil(after.retryMs / 1000)}s`
+      : `wrong key — ${after.attemptsLeft} attempt(s) left`;
+    return reply.code(401).send({ error: 'wrong key', detail });
+  });
+
+  // 로그아웃 — 쿠키 제거(Max-Age=0).
+  app.post('/api/auth/logout', async (req, reply) => {
+    const parts = [`${SESSION_COOKIE}=`, 'Path=/', 'HttpOnly', 'SameSite=Lax', 'Max-Age=0'];
+    if (isSecureReq(req)) parts.push('Secure');
+    reply.header('set-cookie', parts.join('; '));
+    return reply.send({ ok: true });
+  });
+
   // 보드 하이드레이션 — machines/repos/tasks/runs(+events)/captures 한 방에.
   // 기본 view=active: 닫힌 태스크·그 run·이벤트 전량을 내리지 않는다(수백 run 시 페이로드 폭발 방지).
   // 이벤트는 활성 run 당 최근 40개만(카드는 8, 모달은 전량 refetch). view=all 은 구버전 전량.
@@ -219,7 +295,8 @@ export async function buildServer(): Promise<FastifyInstance> {
       // authOpen = 비밀번호 미설정 → Funnel(공개) 가드가 켜져야 함(원격접근 카드용)
       daemon: {
         version: config.version, pid: process.pid, port: config.port, dbPath: config.dbPath,
-        authOpen: config.auth.disabled || config.auth.pass === '',
+        // authOpen = 인증이 실질 열려있음(disabled 또는 아직 키 미설정) → Funnel 가드 켜져야 함
+        authOpen: authIsOpen(),
       },
       providers: listProviders(),
     };
@@ -537,8 +614,12 @@ export async function buildServer(): Promise<FastifyInstance> {
   // ─── Design Mode ───────────────────────────────────────────────
   // 캡처 키: 인증 off 면 자유, on 이면 ?k=<COXPIT_AUTH_PASS> (북마클릿은 basic 헤더 불가)
   const captureKeyOk = (req: { query?: unknown }): boolean => {
-    if (config.auth.disabled || config.auth.pass === '') return config.auth.disabled;
-    return ((req.query ?? {}) as { k?: string }).k === config.auth.pass;
+    const m = authMode();
+    // 인증 꺼짐 → 자유. 아직 키 미설정(setup) → 캡처 불가(키가 없으니 증명 수단 없음).
+    if (m.mode === 'disabled') return true;
+    if (m.mode === 'setup') return false;
+    const k = ((req.query ?? {}) as { k?: string }).k ?? '';
+    return verifyKey(k, m);
   };
   const cors = (reply: { header: (k: string, v: string) => unknown }) => {
     reply.header('access-control-allow-origin', '*');
@@ -591,8 +672,8 @@ export async function buildServer(): Promise<FastifyInstance> {
   // Funnel has no Tailscale-side auth, so coxpit's basic auth is the only gate.
   app.post('/api/remote/funnel', async (req, reply) => {
     const b = (req.body ?? {}) as { on?: boolean };
-    if (b.on === true && (config.auth.disabled || config.auth.pass === '')) {
-      return reply.code(409).send({ error: 'set a password first', code: 'NO_AUTH' });
+    if (b.on === true && authIsOpen()) {
+      return reply.code(409).send({ error: 'set an access key first', code: 'NO_AUTH' });
     }
     return setFunnel(config.port, b.on === true);
   });