elanous 0.2.0 → 0.2.5

package/src/nexus/api/plugins-credentials-api.ts

@@ -0,0 +1,47 @@
+import { debug } from '../../debug/log.js';
+import { credentialStatus, setPluginCredentials } from '../../plugins/install/plugin-credentials.js';
+import { checkAuth, type MetaApiOpts } from './meta-api.js';
+import { jsonResponse } from './json-response.js';
+
+const NAME = /^[a-z0-9][a-z0-9-]{1,39}$/;
+
+function failure(error: unknown): Response {
+  if (error instanceof Error && error.message.startsWith('plugin not installed:')) return jsonResponse({ error: 'not_found' }, 404);
+  if (error instanceof Error && (error.message === 'invalid plugin name' || error.message === 'invalid plugin credential field'
+    || error.message === 'invalid plugin credential fields')) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  return jsonResponse({ error: 'credential_error' }, 500);
+}
+
+export function handlePluginsCredentialsGet(req: Request, name: string, opts: MetaApiOpts, root?: string): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!NAME.test(name)) return jsonResponse({ error: 'bad_request' }, 400);
+  try { return jsonResponse(credentialStatus(name, root), 200); }
+  catch (error) { return failure(error); }
+}
+
+/** `reload` re-spawns the daemon's MCP clients so a running plugin server picks up the new values
+ *  (the spawn reads `pluginEnv` fresh). A failed reload never fails the write — the reply says so. */
+export async function handlePluginsCredentialsPut(req: Request, name: string, opts: MetaApiOpts, root?: string, reload?: () => Promise<unknown>): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!NAME.test(name)) return jsonResponse({ error: 'bad_request' }, 400);
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const fields = body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>).fields : undefined;
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields)
+    || Object.values(fields).some(value => typeof value !== 'string' && value !== null)) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  try {
+    const result = setPluginCredentials(name, fields as Record<string, string | null>, root);
+    debug.log('plugin.credentials', 'set', { plugin: name, fields: Object.keys(fields), count: Object.keys(fields).length });
+    let reloaded = false;
+    if (reload) {
+      try { await reload(); reloaded = true; }
+      catch { debug.log('plugin.credentials', 'reload-failed', { plugin: name }, { level: 'warn' }); }
+    }
+    return jsonResponse({ ...result, reloaded }, 200);
+  } catch (error) { return failure(error); }
+}

package/src/nexus/api/plugins-market.ts

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../../autopilot/state-paths.js';
+import { debug } from '../../debug/log.js';
+import { OFFICIAL_INDEX_KEYS } from '../../market/official-keys.js';
+import { verifyIndex, type MarketplaceIndex } from '../../market/signed-index.js';
+import { installPlugin, listInstalledPlugins, removePlugin, type InstallEvent } from '../../plugins/install/plugin-install.js';
+import { updateMarket, type MarketFetchOptions } from '../../plugins/install/market-fetch.js';
+import { userConfigPath } from '../../user-config.js';
+import { jsonResponse } from './json-response.js';
+import { checkAuth, type MetaApiOpts } from './meta-api.js';
+
+export type MarketSignature = 'ok' | 'missing' | 'unknown-key' | 'malformed' | 'stale';
+export interface MarketPlugin {
+  name: string;
+  version: string;
+  description?: string;
+  category?: string;
+  capabilities: string[];
+  connectors: Array<{ id: string; kind: string; userConfig: Array<{ key: string; label: string; secret: boolean }> }>;
+  graphs?: string[];
+  pricing: MarketplaceIndex['plugins'][number]['ai.elanous']['pricing'];
+  sha256: string;
+}
+export interface MarketIndexResponse {
+  markets: Array<{ name: string; signature: MarketSignature; detail?: string; plugins: MarketPlugin[] }>;
+}
+
+function projectPlugins(index: unknown, market: string): MarketPlugin[] {
+  if (!index || typeof index !== 'object') return [];
+  const value = index as Partial<MarketplaceIndex>;
+  if (value.name !== market || !Array.isArray(value.plugins)) return [];
+  return value.plugins.flatMap((plugin): MarketPlugin[] => {
+    if (!plugin || typeof plugin.name !== 'string' || typeof plugin.version !== 'string' ||
+      typeof plugin.artifact?.sha256 !== 'string' || !plugin['ai.elanous'] ||
+      !Array.isArray(plugin['ai.elanous'].capabilities) || !Array.isArray(plugin['ai.elanous'].connectors) ||
+      !plugin['ai.elanous'].pricing || typeof plugin['ai.elanous'].pricing.model !== 'string') return [];
+    const ai = plugin['ai.elanous'];
+    return [{
+      name: plugin.name, version: plugin.version,
+      ...(typeof plugin.description === 'string' ? { description: plugin.description } : {}),
+      ...(typeof plugin.category === 'string' ? { category: plugin.category } : {}),
+      capabilities: ai.capabilities.filter((item): item is string => typeof item === 'string'),
+      connectors: ai.connectors.flatMap(connector => {
+        if (!connector || typeof connector.id !== 'string' || typeof connector.kind !== 'string' || !Array.isArray(connector.userConfig)) return [];
+        return [{ id: connector.id, kind: connector.kind, userConfig: connector.userConfig.flatMap(field =>
+          field && typeof field.key === 'string' && typeof field.label === 'string' && typeof field.secret === 'boolean'
+            ? [{ key: field.key, label: field.label, secret: field.secret }] : []) }];
+      }),
+      ...(Array.isArray(ai.graphs) ? { graphs: ai.graphs.filter((item): item is string => typeof item === 'string') } : {}),
+      pricing: {
+        model: ai.pricing.model,
+        ...(typeof ai.pricing.amount === 'number' ? { amount: ai.pricing.amount } : {}),
+        ...(typeof ai.pricing.currency === 'string' ? { currency: ai.pricing.currency } : {}),
+        ...(typeof ai.pricing.period === 'string' ? { period: ai.pricing.period } : {}),
+      },
+      sha256: plugin.artifact.sha256,
+    }];
+  });
+}
+
+export function readMarketIndex(root = elanousStateRoot(), trustedKeys: ReadonlyArray<{ keyId: string; publicKey: string }> = []): MarketIndexResponse {
+  const base = join(root, 'markets');
+  const markets: MarketIndexResponse['markets'] = [];
+  if (existsSync(base)) for (const entry of readdirSync(base, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(base, entry.name);
+    const indexPath = [join(dir, 'marketplace.json'), join(dir, '.agents', 'plugins', 'marketplace.json')].find(existsSync);
+    if (!indexPath) {
+      markets.push({ name: entry.name, signature: 'malformed', detail: '마켓 인덱스를 찾지 못했습니다.', plugins: [] });
+      continue;
+    }
+    let signature: MarketSignature = 'missing';
+    let detail: string | undefined;
+    let index: unknown;
+    try {
+      const bytes = readFileSync(indexPath);
+      const signaturePath = join(dirname(indexPath), 'index.sig');
+      if (existsSync(signaturePath)) {
+        const checked = verifyIndex({ marketplaceBytes: bytes, signatureText: readFileSync(signaturePath, 'utf8'), trustedKeys: [...OFFICIAL_INDEX_KEYS, ...trustedKeys] });
+        if (checked.ok) { signature = 'ok'; index = checked.index; }
+        else {
+          signature = checked.reason === 'unknown-key' ? 'unknown-key' : checked.reason === 'malformed' ? 'malformed' : 'stale';
+          detail = checked.detail;
+        }
+      }
+      if (!index) index = JSON.parse(bytes.toString('utf8')) as unknown;
+    } catch {
+      signature = 'malformed';
+      detail = 'marketplace.json or index.sig could not be read';
+    }
+    const plugins = projectPlugins(index, entry.name);
+    if (!index || !Array.isArray((index as MarketplaceIndex).plugins) || (index as MarketplaceIndex).name !== entry.name) {
+      signature = 'malformed';
+      detail = 'marketplace.json: invalid market index';
+    }
+    markets.push({ name: entry.name, signature, ...(detail ? { detail: '마켓 인덱스를 확인하지 못했습니다.' } : {}), plugins });
+  }
+  markets.sort((a, b) => a.name.localeCompare(b.name));
+  debug.log('nexus.plugins-market', 'index', { markets: markets.length, ok: markets.filter(m => m.signature === 'ok').length, notOk: markets.filter(m => m.signature !== 'ok').length });
+  return { markets };
+}
+
+function configuredTrustedKeys(path = userConfigPath()): Array<{ keyId: string; publicKey: string }> {
+  try {
+    const config: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!config || typeof config !== 'object' || Array.isArray(config)) return [];
+    const market = (config as Record<string, unknown>).market;
+    if (!market || typeof market !== 'object' || Array.isArray(market)) return [];
+    const keys = (market as Record<string, unknown>).trustedKeys;
+    if (!Array.isArray(keys)) return [];
+    return keys.filter((key): key is { keyId: string; publicKey: string } =>
+      key !== null && typeof key === 'object' && !Array.isArray(key) &&
+      typeof key.keyId === 'string' && typeof key.publicKey === 'string');
+  } catch { return []; }
+}
+
+export function handlePluginsIndexGet(req: Request, opts: MetaApiOpts, root?: string, configPath?: string): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  return jsonResponse(readMarketIndex(root, configuredTrustedKeys(configPath)));
+}
+
+export function handlePluginsGet(req: Request, opts: MetaApiOpts, root?: string): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  return jsonResponse(listInstalledPlugins(root));
+}
+
+const MARKET_NAME = /^[a-z0-9][a-z0-9-]{1,39}$/;
+const MARKET_SPEC = /^[a-z0-9][a-z0-9-]{1,39}@[a-z0-9][a-z0-9-]{1,39}$/;
+
+/** 실패 원인 한 줄 — 사용자가 «왜» 를 볼 수 있게(2026-09-29 실물: «설치 중 오류가 발생했습니다» 만 보여 아티팩트 누락을 못 봤다). 홈 경로는 `~` 로 · 200자 · 한 줄. */
+export function safeDetail(error: unknown): string | undefined {
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : undefined;
+  if (!message) return undefined;
+  return message.replace(/\/(?:Users|home)\/[^/\s]+/g, '~').replace(/\s+/g, ' ').trim().slice(0, 200) || undefined;
+}
+
+function safeReason(error: unknown): string {
+  const reason = error && typeof error === 'object' && 'reason' in error ? error.reason : undefined;
+  return typeof reason === 'string' && ['signature', 'scan', 'consent-denied', 'credentials', 'conflict', 'io'].includes(reason)
+    ? reason : 'io';
+}
+
+export async function handlePluginsMarketRefresh(req: Request, name: string, opts: MetaApiOpts, fetchOptions: MarketFetchOptions = {}): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!MARKET_NAME.test(name)) return jsonResponse({ ok: false, reason: 'invalid-market' }, 400);
+  try {
+    const result = await updateMarket(name, fetchOptions);
+    const plugins = projectPlugins(result.index, name);
+    debug.log('nexus.plugins-market', 'refresh', { name, ok: true, count: plugins.length });
+    return jsonResponse({ ok: true, plugins });
+  } catch (error) {
+    const reason = safeReason(error);
+    debug.log('nexus.plugins-market', 'refresh', { name, ok: false, reason });
+    return jsonResponse({ ok: false, reason });
+  }
+}
+
+export async function handlePluginsInstall(req: Request, opts: MetaApiOpts, root?: string, configPath?: string): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  let body: unknown;
+  try { body = await req.json(); } catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const input = body as { spec?: unknown; acceptedCapabilities?: unknown } | null;
+  if (!input || typeof input.spec !== 'string' || !MARKET_SPEC.test(input.spec) ||
+    !Array.isArray(input.acceptedCapabilities) || !input.acceptedCapabilities.every(cap => typeof cap === 'string')) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  const spec = input.spec;
+  const accepted = new Set(input.acceptedCapabilities as string[]);
+  const trustedKeys = configuredTrustedKeys(configPath);
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      const send = (value: Record<string, unknown>) => controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`));
+      const onEvent = (event: InstallEvent) => {
+        if (event.event === 'consent') send({ event: 'consent', capabilities: event.capabilities, required: event.required });
+        else if (event.event === 'credentials') send({ event: 'credentials', required: event.connectors.some(c => c.fields.length > 0) });
+        else send({ event: event.event });
+      };
+      try {
+        await installPlugin(spec, {
+          ...(root ? { root } : {}), trustedKeys: [...OFFICIAL_INDEX_KEYS, ...trustedKeys],
+          onEvent, consent: capabilities => capabilities.every(cap => accepted.has(cap)),
+        });
+        debug.log('nexus.plugins-market', 'install', { spec, ok: true });
+      } catch (error) {
+        const reason = safeReason(error);
+        const detail = safeDetail(error);
+        debug.log('nexus.plugins-market', 'install', { spec, ok: false, reason, ...(detail ? { detail } : {}) });
+        send({ event: 'failed', reason, ...(detail ? { detail } : {}) });
+      } finally { controller.close(); }
+    },
+  });
+  return new Response(stream, { headers: { 'content-type': 'application/x-ndjson; charset=utf-8', 'cache-control': 'no-store' } });
+}
+
+export function handlePluginsRemove(req: Request, name: string, opts: MetaApiOpts, root?: string): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!MARKET_NAME.test(name)) return jsonResponse({ error: 'bad_request' }, 400);
+  try {
+    const removed = removePlugin(name, root);
+    debug.log('nexus.plugins-market', 'remove', { name, removed });
+    return jsonResponse({ removed });
+  } catch (error) {
+    const reason = safeReason(error);
+    debug.log('nexus.plugins-market', 'remove', { name, reason });
+    return jsonResponse({ error: reason }, 500);
+  }
+}

package/src/nexus/api/pod-credential-api.ts

@@ -0,0 +1,187 @@
+/** POST /v1/pod/credential/grok — Pod 가 만료 전에 새 grok access 만 받는 문.
+ *
+ *  인증은 넥서스 bearer 가 아니다. `mintGroundingToken({ scope: 'llm-credential' })` 만 통과한다.
+ *  응답 키는 `key`·`expires_at` 둘뿐. refresh·계정 id·파일 경로는 응답·로그·에러에 싣지 않는다.
+ */
+import { debug } from '../../debug/log.js';
+import { githubInstallationCredential } from '../../auth/github-app-token.js';
+import { verifyGroundingToken, type GroundingTokenDeps, type GroundingTokenScope } from '../../grounding/token.js';
+import { isGrokSubscriptionExpiring, readGrokSubscriptionAccess, refreshGrokSubscriptionToken } from '../../grok/credential.js';
+
+export const POD_CREDENTIAL_GROK_PATH = '/v1/pod/credential/grok';
+export const POD_CREDENTIAL_GITHUB_PATH = '/v1/pod/credential/github';
+export const POD_GITHUB_CREDENTIAL_TOKEN_ENV = 'ELANOUS_POD_GITHUB_CREDENTIAL_TOKEN';
+export const POD_GITHUB_CREDENTIAL_URL_ENV = 'ELANOUS_POD_GITHUB_CREDENTIAL_URL';
+/** 만료까지 이 안이면 기존 호스트 갱신(`refreshGrokSubscriptionToken`)을 한 번 부른다. */
+export const POD_CREDENTIAL_HOST_REFRESH_WINDOW_MS = 10 * 60 * 1000;
+/** runId 당 분당 1회. */
+export const POD_CREDENTIAL_PER_RUN_PER_MIN = 1;
+/** ⓢ6 — 토큰이 새어 runId 를 늘려도 막는 프로세스 전역 분당 상한. */
+export const POD_CREDENTIAL_GLOBAL_PER_MIN = 30;
+
+export type PodCredentialReason = 'expired' | 'revoked' | 'scope' | 'rate' | 'unauthorized' | 'unavailable';
+
+export interface PodCredentialDeps {
+  readonly token?: GroundingTokenDeps;
+  readonly now?: () => number;
+  readonly home?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  /** 테스트 심 — 호스트 grok 바이너리 대신. */
+  readonly refreshExec?: (cmd: string, args: string[], timeoutMs: number) => void;
+  readonly loadAccess?: (home: string | undefined, env: NodeJS.ProcessEnv) => { key: string; expiresAt: string } | null;
+}
+
+export interface PodGithubCredentialDeps {
+  readonly token?: GroundingTokenDeps;
+  readonly now?: () => number;
+  readonly mintInstallation?: (repository: string) => { token: string; expires_at: string } | null;
+  readonly installationRepositories?: (token: string) => Promise<readonly string[] | null>;
+}
+
+interface HitWindow {
+  readonly stamps: number[];
+}
+
+const hitsByRun = new Map<string, HitWindow>();
+const globalHits: number[] = [];
+const githubHitsByRun = new Map<string, HitWindow>();
+const githubGlobalHits: number[] = [];
+
+export function resetPodCredentialRateForTesting(): void {
+  hitsByRun.clear();
+  globalHits.length = 0;
+  githubHitsByRun.clear();
+  githubGlobalHits.length = 0;
+}
+
+function prune(stamps: number[], now: number): number[] {
+  return stamps.filter((t) => now - t < 60_000);
+}
+
+function takeRate(runId: string, now: number, byRun = hitsByRun, all = globalHits): boolean {
+  const prev = prune(byRun.get(runId)?.stamps ?? [], now);
+  const global = prune(all, now);
+  all.length = 0;
+  all.push(...global);
+  if (prev.length >= POD_CREDENTIAL_PER_RUN_PER_MIN || all.length >= POD_CREDENTIAL_GLOBAL_PER_MIN) {
+    byRun.set(runId, { stamps: prev });
+    return false;
+  }
+  prev.push(now);
+  all.push(now);
+  byRun.set(runId, { stamps: prev });
+  return true;
+}
+
+function bearerOf(req: Request): string | null {
+  const raw = req.headers.get('authorization') ?? req.headers.get('Authorization');
+  if (!raw) return null;
+  const m = /^Bearer\s+(\S+)$/.exec(raw.trim());
+  return m?.[1] ?? null;
+}
+
+function reasonResponse(status: number, reason: PodCredentialReason): Response {
+  return Response.json({ reason }, { status });
+}
+
+function defaultLoad(home: string | undefined, _env: NodeJS.ProcessEnv, refreshExec?: PodCredentialDeps['refreshExec'], now?: () => number): { key: string; expiresAt: string } | null {
+  if (isGrokSubscriptionExpiring({
+    ...(home ? { home } : {}),
+    bufferMs: POD_CREDENTIAL_HOST_REFRESH_WINDOW_MS,
+    ...(now ? { now } : {}),
+  })) {
+    refreshGrokSubscriptionToken({
+      ...(home ? { home } : {}),
+      ...(refreshExec ? { execImpl: refreshExec } : {}),
+    });
+  }
+  const access = readGrokSubscriptionAccess(home);
+  if (!access?.expiresAt) return null;
+  return { key: access.key, expiresAt: access.expiresAt };
+}
+
+/** 핸들러 몸. http-server 는 이 함수를 부르기 «전»에 `authenticatePodCredential` 을 먼저 부른다. */
+export async function handlePodGrokCredential(req: Request, deps: PodCredentialDeps = {}): Promise<Response> {
+  const gate = await authenticatePodCredential(req, deps);
+  if (!gate.ok) return gate.response;
+  const now = (deps.now ?? Date.now)();
+  if (!takeRate(gate.runId, now)) return reasonResponse(429, 'rate');
+
+  const env = deps.env ?? process.env;
+  let loaded: { key: string; expiresAt: string } | null;
+  try {
+    loaded = deps.loadAccess
+      ? deps.loadAccess(deps.home, env)
+      : defaultLoad(deps.home, env, deps.refreshExec, deps.now);
+  } catch {
+    return reasonResponse(503, 'unavailable');
+  }
+  if (!loaded || !loaded.key) return reasonResponse(503, 'unavailable');
+
+  const expiresAt = loaded.expiresAt;
+  debug.log('pod.credential', 'grok-issued', { runId: gate.runId, job: gate.job, expiresAt });
+  debug.log('pod.credential', 'issuance', { runId: gate.runId, job: gate.job, exp: gate.exp });
+  return Response.json({ key: loaded.key, expires_at: expiresAt });
+}
+
+export async function installationRepositories(token: string): Promise<readonly string[] | null> {
+  const response = await fetch('https://api.github.com/installation/repositories?per_page=100', {
+    headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28' },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) return null;
+  const data: unknown = await response.json();
+  if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray((data as { repositories?: unknown }).repositories)) return null;
+  const body = data as { total_count?: unknown; repositories: unknown[] };
+  if (body.repositories.length !== 1 || body.total_count !== 1) return null;
+  const name = body.repositories[0] && typeof body.repositories[0] === 'object' && !Array.isArray(body.repositories[0]) ? (body.repositories[0] as { full_name?: unknown }).full_name : undefined;
+  return typeof name === 'string' ? [name] : null;
+}
+
+/** No repository is accepted from the request body: the host signed its owner/name into the run token. */
+export async function handlePodGithubCredential(req: Request, deps: PodGithubCredentialDeps = {}): Promise<Response> {
+  const gate = await authenticatePodCredential(req, deps, 'gh-credential');
+  if (!gate.ok) return gate.response;
+  if (!gate.repository || !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(gate.repository)) return Response.json({ error: 'unauthorized' }, { status: 401 });
+  if (!takeRate(gate.runId, (deps.now ?? Date.now)(), githubHitsByRun, githubGlobalHits)) return reasonResponse(429, 'rate');
+
+  let issued: { token: string; expires_at: string } | null;
+  try {
+    issued = (deps.mintInstallation ?? ((repository) => githubInstallationCredential({ scope: { repository: repository.split('/')[1]! } })))(gate.repository);
+  } catch {
+    return reasonResponse(503, 'unavailable');
+  }
+  if (!issued?.token || typeof issued.expires_at !== 'string' || !Number.isFinite(Date.parse(issued.expires_at)) || Date.parse(issued.expires_at) <= (deps.now ?? Date.now)()) return reasonResponse(503, 'unavailable');
+  try {
+    const available = await (deps.installationRepositories ?? installationRepositories)(issued.token);
+    if (available?.length !== 1 || available[0]?.toLowerCase() !== gate.repository.toLowerCase()) return reasonResponse(503, 'unavailable');
+  } catch {
+    return reasonResponse(503, 'unavailable');
+  }
+  debug.log('pod.credential', 'github-issued', { runId: gate.runId, job: gate.job, expiresAt: issued.expires_at });
+  return Response.json({ token: issued.token, expires_at: issued.expires_at });
+}
+
+/**
+ * 쓰기 관문. 본문을 읽지 않는다. 토큰이 없거나 서명이 깨지면 401,
+ * scope·만료·회수는 403 과 사유만.
+ */
+export async function authenticatePodCredential(
+  req: Request,
+  deps: Pick<PodCredentialDeps, 'token'> = {},
+  expectedScope: GroundingTokenScope = 'llm-credential',
+): Promise<
+  | { readonly ok: true; readonly runId: string; readonly job: string; readonly repository?: string; readonly exp: number }
+  | { readonly ok: false; readonly response: Response }
+> {
+  const token = bearerOf(req);
+  if (!token) return { ok: false, response: Response.json({ error: 'unauthorized' }, { status: 401 }) };
+  const verified = await verifyGroundingToken(token, { ...(deps.token ?? {}), expectedScope });
+  if (!verified.ok) {
+    if (verified.reason === 'expired' || verified.reason === 'revoked' || verified.reason === 'scope') {
+      return { ok: false, response: reasonResponse(403, verified.reason) };
+    }
+    return { ok: false, response: Response.json({ error: 'unauthorized' }, { status: 401 }) };
+  }
+  return { ok: true, runId: verified.runId, job: verified.job, ...(verified.repository ? { repository: verified.repository } : {}), exp: verified.exp };
+}

package/src/nexus/api/public-routes.ts

@@ -0,0 +1,87 @@
+// NEXUS `/v1` default-deny allowlist — one code constant.
+//
+// `routeRequest` calls `isPublicRoute` before any handler. A `/v1/` path
+// that is not listed here must pass the existing `checkAuth` (same-origin
+// exemption + constant-time bearer). Static `/app/*` and `/` are outside
+// `/v1` and are not gate subjects.
+//
+// Callbacks and webhooks stay off this list:
+//   - `handleHitlCallback` (`src/nexus/api/meta-api.ts`) calls `checkAuth`
+//     itself; it does not verify a callback signature or token of its own.
+//   - `checkAuth` (`src/workflow-runtime/triggers/webhook-router.ts`)
+//     returns success when the registered trigger has no `auth`, so an
+//     unauthenticated POST can still dispatch a workflow.
+
+export type PublicRouteMatch = 'exact' | 'prefix';
+
+export interface PublicRoute {
+  method: string;
+  match: PublicRouteMatch;
+  path: string;
+  why: string;
+  /** The handler verifies its own credential (not the nexus bearer) and may answer 401 itself. */
+  selfVerified?: true;
+}
+
+export const PUBLIC_ROUTES: Array<PublicRoute> = [
+  {
+    method: 'GET',
+    match: 'exact',
+    path: '/v1/health',
+    why: 'liveness probe and setup-mode signal (F condition 2)',
+  },
+  {
+    method: 'GET',
+    match: 'exact',
+    path: '/v1/push/vapid-public-key',
+    why: 'PWA fetches the VAPID public key before a bearer is pasted',
+  },
+  {
+    method: 'GET',
+    match: 'exact',
+    path: '/v1/nexus/connect-info',
+    why: 'connect metadata only; auto_token removed in #20782',
+  },
+  {
+    method: 'POST',
+    match: 'exact',
+    path: '/v1/pod/credential/grok',
+    selfVerified: true,
+    why: 'Pod grok access relay (#20789); Pods hold no nexus bearer — pod-credential-api.ts verifies its own llm-credential token (verifyGroundingToken expectedScope) before reading the body',
+  },
+  {
+    method: 'POST',
+    match: 'exact',
+    path: '/v1/pod/credential/github',
+    selfVerified: true,
+    why: 'Pod GitHub App credential relay verifies its own run-scoped gh-credential token before minting a repository-scoped installation token',
+  },
+  {
+    method: 'GET',
+    match: 'prefix',
+    path: '/v1/setup/',
+    why: 'setup wizard routes; public only while setupMode is true (P24b)',
+  },
+];
+
+export interface PublicRouteContext {
+  setupMode: boolean;
+}
+
+/** True when this method+pathname is on the public allowlist. */
+export function isPublicRoute(
+  method: string,
+  pathname: string,
+  ctx: PublicRouteContext,
+): boolean {
+  for (const route of PUBLIC_ROUTES) {
+    if (route.method !== method) continue;
+    if (route.path.startsWith('/v1/setup/') && !ctx.setupMode) continue;
+    if (route.match === 'exact') {
+      if (pathname === route.path) return true;
+    } else if (pathname === route.path || pathname.startsWith(route.path)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/nexus/api/rest-route-paths.ts

@@ -32,9 +32,24 @@
  *  bun test test/rest-route-paths-single-home.test.ts
  *  ``` */
 
+/** `POST /v1/design-direction` — owner-authenticated repository design direction selection. */
+export const DESIGN_DIRECTION_PATH = '/v1/design-direction';
+
+/** `POST /v1/design-system` — owner-authenticated custom system from a URL or a palette. */
+export const DESIGN_SYSTEM_PATH = '/v1/design-system';
+
+/** `GET /v1/design-previews` — HTML previews under the resolved repository. */
+export const DESIGN_PREVIEWS_PATH = '/v1/design-previews';
+
+/** `GET /v1/design-previews/<system>` — one preview document. */
+export const DESIGN_PREVIEW_PATH_PREFIX = '/v1/design-previews/';
+
 /** `GET /v1/devices` — 디바이스 함대 스냅샷. */
 export const DEVICES_PATH = '/v1/devices';
 
+/** Owner-only idea PR review and merge. */
+export const APPROVALS_MERGES_PATH = '/v1/approvals/merges';
+
 /** `POST /v1/templates/capability-preview` — 템플릿 능력 미리보기.
  *  📏 이 여섯째는 앞 다섯을 접자 «자가 곧바로 다음 후보로 올려 준 것»이다 — 같은 부류라 같이 접었다. */
 export const TEMPLATE_CAPABILITY_PREVIEW_PATH = '/v1/templates/capability-preview';

package/src/nexus/api/schedules-action.ts

@@ -18,9 +18,13 @@ interface ScheduleActionBody {
   command?: string;
   category?: string;
   note?: string;
+  confirm?: boolean;
 }
 
-export async function handleSchedulesActionPost(req: Request): Promise<Response> {
+export async function handleSchedulesActionPost(
+  req: Request,
+  dispatch?: (args: Record<string, unknown>) => Promise<unknown>,
+): Promise<Response> {
   let body: ScheduleActionBody;
   try {
     body = (await req.json()) as ScheduleActionBody;
@@ -29,9 +33,14 @@ export async function handleSchedulesActionPost(req: Request): Promise<Response>
   }
   const action = typeof body.action === 'string' ? body.action.trim() : '';
   if (!action) return jsonResponse({ error: 'action 필수 (adopt/release/enable/disable/delete/update/create)' }, 400);
+  if (['delete', 'migrate', 'adopt', 'release'].includes(action) && body.confirm !== true) {
+    const id = typeof body.id === 'string' ? body.id : '';
+    return jsonResponse({ dryRun: true, action, id,
+      plan: `${id || '(id 미지정)'}: ${action} 적용 예정 — confirm:true 로 확인 후 실행.` });
+  }
 
-  const { dispatchScheduleManage } = await import('../../domains/schedule-manage-tool.js');
-  const result = await dispatchScheduleManage({
+  const run = dispatch ?? (await import('../../domains/schedule-manage-tool.js')).dispatchScheduleManage;
+  const result = await run({
     action,
     ...(body.id !== undefined ? { id: body.id } : {}),
     ...(body.cron !== undefined ? { cron: body.cron } : {}),