@obov/mext 0.5.0 → 0.7.1

package/dist/mcp/help.js

@@ -50,6 +50,8 @@ function commandSummary(entry, options) {
         destructive: c.destructive,
         requiresConfirmation: c.requiresConfirmation,
     };
+    if (c.needsApproval !== undefined)
+        out.needsApproval = "conditional";
     const tool = options.toolFor?.(entry);
     if (tool !== undefined)
         out.tool = tool;
@@ -61,7 +63,8 @@ function commandHelp(entry, options) {
     const errors = ["INVALID_ARGUMENT"];
     if (!c.readOnly || c.scopes.length > 0)
         errors.push("UNAUTHENTICATED", "PERMISSION_DENIED");
-    if (c.requiresConfirmation)
+    // 승인 (항상 · 조건식) = ask 방식의 확인 오류. APPROVAL_REQUIRED 는 표면 설정 · 행위자에 따라 승인 명령어 모두에서 가능 (§4 승인)
+    if (c.requiresConfirmation || c.needsApproval !== undefined)
         errors.push("INPUT_UNAVAILABLE", "INPUT_DECLINED");
     const out = { kind: "command", ...meta, errors };
     const tool = options.toolFor?.(entry);
@@ -131,6 +134,8 @@ function safetyFlags(c) {
         flags.push("destructive");
     if (c.requiresConfirmation)
         flags.push("requires confirmation");
+    else if (c.needsApproval !== undefined)
+        flags.push("may require confirmation");
     return flags.join(", ");
 }
 //# sourceMappingURL=help.js.map

package/dist/mcp/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/mcp/help.ts"],"names":[],"mappings":"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","sourcesContent":["import { findCommand } from \"../invoke.ts\"\nimport { describeCommand, type ManifestCommand } from \"../manifest.ts\"\nimport type { RegisteredCommand, Registry } from \"../registry.ts\"\n\n/** help 의 예약 명령어 이름. 루트 세그먼트 help 는 Registry 에서 금지 */\nexport const HELP_COMMAND = \"help\"\n\nexport interface HelpNamespaceSummary {\n  id: string\n  /** _index.md 첫 줄 */\n  description?: string\n}\n\nexport interface HelpCommandSummary {\n  id: string\n  description: string\n  readOnly: boolean\n  destructive: boolean\n  requiresConfirmation: boolean\n  /** split 노출에서 이 명령어를 호출할 도구 (query · mutate). execute 노출에서는 없음 */\n  tool?: string\n}\n\n/** execute({ command: \"help\" }) */\nexport interface RootHelp {\n  kind: \"root\"\n  /** commands/_index.md */\n  description?: string\n  namespaces: HelpNamespaceSummary[]\n  /** 루트 직속 명령어 */\n  commands: HelpCommandSummary[]\n}\n\n/** execute({ command: \"help\", args: { target: \"users\" } }) */\nexport interface NamespaceHelp {\n  kind: \"namespace\"\n  id: string\n  /** _index.md 전체 */\n  description?: string\n  namespaces: HelpNamespaceSummary[]\n  commands: HelpCommandSummary[]\n  /** 같은 ID 의 명령어 (users/index.ts) */\n  command?: CommandHelp\n}\n\n/** execute({ command: \"help\", args: { target: \"users.get\" } }) */\nexport interface CommandHelp extends Omit<ManifestCommand, \"file\"> {\n  kind: \"command\"\n  /** 이 명령어 호출이 돌려줄 수 있는 구조화 오류 code */\n  errors: string[]\n  tool?: string\n}\n\nexport type Help = RootHelp | NamespaceHelp | CommandHelp\n\nexport interface HelpOptions {\n  /** 명령어 → 호출할 도구 이름. split 노출이 지정 */\n  toolFor?: (entry: RegisteredCommand) => string | undefined\n}\n\n/**\n * help 3단계: target 없음 = 루트 (네임스페이스 · 루트 명령어), 네임스페이스 ID = 그 명령어 목록,\n * 명령어 ID · 별칭 = 설명 · 입력 스키마 · 예시 · 오류 · 권한. 없는 target = UNKNOWN_COMMAND.\n */\nexport function help(registry: Registry, target: string | undefined, options: HelpOptions = {}): Help {\n  const id = target?.trim() ?? \"\"\n  if (id === \"\") {\n    const root = registry.namespaces.get(\"\")!\n    const out: RootHelp = {\n      kind: \"root\",\n      namespaces: root.namespaces.map((n) => namespaceSummary(registry, n)),\n      commands: root.commands.map((c) => commandSummary(registry.commands.get(c)!, options)),\n    }\n    if (root.description !== undefined) out.description = root.description\n    return out\n  }\n  const ns = registry.namespaces.get(id)\n  if (ns) {\n    const out: NamespaceHelp = {\n      kind: \"namespace\",\n      id,\n      namespaces: ns.namespaces.map((n) => namespaceSummary(registry, n)),\n      commands: ns.commands.map((c) => commandSummary(registry.commands.get(c)!, options)),\n    }\n    if (ns.description !== undefined) out.description = ns.description\n    const self = registry.commands.get(id)\n    if (self) out.command = commandHelp(self, options)\n    return out\n  }\n  return commandHelp(findCommand(registry, id), options)\n}\n\nfunction namespaceSummary(registry: Registry, id: string): HelpNamespaceSummary {\n  const description = registry.namespaces.get(id)?.description\n  const first = description?.split(\"\\n\").find((l) => l.trim() !== \"\")\n  return first === undefined ? { id } : { id, description: first.replace(/^#+\\s*/, \"\").trim() }\n}\n\nfunction commandSummary(entry: RegisteredCommand, options: HelpOptions): HelpCommandSummary {\n  const c = entry.command\n  const out: HelpCommandSummary = {\n    id: entry.id,\n    description: c.description,\n    readOnly: c.readOnly,\n    destructive: c.destructive,\n    requiresConfirmation: c.requiresConfirmation,\n  }\n  const tool = options.toolFor?.(entry)\n  if (tool !== undefined) out.tool = tool\n  return out\n}\n\nfunction commandHelp(entry: RegisteredCommand, options: HelpOptions): CommandHelp {\n  const { file: _file, ...meta } = describeCommand(entry)\n  const c = entry.command\n  const errors = [\"INVALID_ARGUMENT\"]\n  if (!c.readOnly || c.scopes.length > 0) errors.push(\"UNAUTHENTICATED\", \"PERMISSION_DENIED\")\n  if (c.requiresConfirmation) errors.push(\"INPUT_UNAVAILABLE\", \"INPUT_DECLINED\")\n  const out: CommandHelp = { kind: \"command\", ...meta, errors }\n  const tool = options.toolFor?.(entry)\n  if (tool !== undefined) out.tool = tool\n  return out\n}\n\n/** help 의 사람용 텍스트 (MCP text content). 구조는 structuredContent 가 원본 */\nexport function formatHelp(value: Help, call = \"execute\"): string {\n  const lines: string[] = []\n  const hint = (target: string) => `${call}({ command: \"help\", args: { target: \"${target}\" } })`\n  const listCommands = (commands: HelpCommandSummary[]) => {\n    if (commands.length === 0) return\n    lines.push(\"Commands:\")\n    const width = Math.max(...commands.map((c) => c.id.length))\n    for (const c of commands) {\n      const flags = safetyFlags(c)\n      const via = c.tool !== undefined ? ` (via ${c.tool})` : \"\"\n      lines.push(`  ${c.id.padEnd(width)}  ${c.description}${flags ? ` [${flags}]` : \"\"}${via}`)\n    }\n  }\n  const listNamespaces = (namespaces: HelpNamespaceSummary[]) => {\n    if (namespaces.length === 0) return\n    lines.push(\"Namespaces:\")\n    const width = Math.max(...namespaces.map((n) => n.id.length))\n    for (const n of namespaces) lines.push(`  ${n.id.padEnd(width)}  ${n.description ?? \"\"}`.trimEnd())\n  }\n\n  if (value.kind === \"command\") {\n    lines.push(`${value.id}: ${value.description}`)\n    if (value.aliases.length > 0) lines.push(`Aliases: ${value.aliases.join(\", \")}`)\n    const flags = safetyFlags(value)\n    lines.push(`Safety: ${flags || \"none\"}`)\n    if (value.scopes.length > 0) lines.push(`Scopes: ${value.scopes.join(\", \")}`)\n    if (value.tool !== undefined) lines.push(`Tool: ${value.tool}`)\n    lines.push(\"Input schema:\", JSON.stringify(value.inputSchema, null, 2))\n    if (value.examples.length > 0) {\n      lines.push(\"Examples:\")\n      for (const e of value.examples) lines.push(`  ${JSON.stringify(e)}`)\n    }\n    lines.push(`Errors: ${value.errors.join(\", \")}`)\n    return lines.join(\"\\n\")\n  }\n\n  if (value.kind === \"namespace\") lines.push(value.id)\n  if (value.description !== undefined) lines.push(value.description, \"\")\n  listNamespaces(value.namespaces)\n  listCommands(value.commands)\n  if (value.kind === \"namespace\" && value.command !== undefined) {\n    lines.push(\"\", formatHelp(value.command, call))\n  }\n  lines.push(\"\", `Details: ${hint(value.kind === \"root\" ? \"<namespace or command>\" : `${value.id}.<command>`)}`)\n  return lines.join(\"\\n\").replace(/^\\n+/, \"\")\n}\n\nfunction safetyFlags(c: { readOnly: boolean; destructive: boolean; requiresConfirmation: boolean }): string {\n  const flags: string[] = []\n  if (c.readOnly) flags.push(\"read-only\")\n  if (c.destructive) flags.push(\"destructive\")\n  if (c.requiresConfirmation) flags.push(\"requires confirmation\")\n  return flags.join(\", \")\n}\n"]}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/mcp/help.ts"],"names":[],"mappings":"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","sourcesContent":["import { findCommand } from \"../invoke.ts\"\nimport { describeCommand, type ManifestCommand } from \"../manifest.ts\"\nimport type { RegisteredCommand, Registry } from \"../registry.ts\"\n\n/** help 의 예약 명령어 이름. 루트 세그먼트 help 는 Registry 에서 금지 */\nexport const HELP_COMMAND = \"help\"\n\nexport interface HelpNamespaceSummary {\n  id: string\n  /** _index.md 첫 줄 */\n  description?: string\n}\n\nexport interface HelpCommandSummary {\n  id: string\n  description: string\n  readOnly: boolean\n  destructive: boolean\n  requiresConfirmation: boolean\n  /** 승인이 조건식일 때만 (§4 승인) */\n  needsApproval?: \"conditional\"\n  /** split 노출에서 이 명령어를 호출할 도구 (query · mutate). execute 노출에서는 없음 */\n  tool?: string\n}\n\n/** execute({ command: \"help\" }) */\nexport interface RootHelp {\n  kind: \"root\"\n  /** commands/_index.md */\n  description?: string\n  namespaces: HelpNamespaceSummary[]\n  /** 루트 직속 명령어 */\n  commands: HelpCommandSummary[]\n}\n\n/** execute({ command: \"help\", args: { target: \"users\" } }) */\nexport interface NamespaceHelp {\n  kind: \"namespace\"\n  id: string\n  /** _index.md 전체 */\n  description?: string\n  namespaces: HelpNamespaceSummary[]\n  commands: HelpCommandSummary[]\n  /** 같은 ID 의 명령어 (users/index.ts) */\n  command?: CommandHelp\n}\n\n/** execute({ command: \"help\", args: { target: \"users.get\" } }) */\nexport interface CommandHelp extends Omit<ManifestCommand, \"file\"> {\n  kind: \"command\"\n  /** 이 명령어 호출이 돌려줄 수 있는 구조화 오류 code */\n  errors: string[]\n  tool?: string\n}\n\nexport type Help = RootHelp | NamespaceHelp | CommandHelp\n\nexport interface HelpOptions {\n  /** 명령어 → 호출할 도구 이름. split 노출이 지정 */\n  toolFor?: (entry: RegisteredCommand) => string | undefined\n}\n\n/**\n * help 3단계: target 없음 = 루트 (네임스페이스 · 루트 명령어), 네임스페이스 ID = 그 명령어 목록,\n * 명령어 ID · 별칭 = 설명 · 입력 스키마 · 예시 · 오류 · 권한. 없는 target = UNKNOWN_COMMAND.\n */\nexport function help(registry: Registry, target: string | undefined, options: HelpOptions = {}): Help {\n  const id = target?.trim() ?? \"\"\n  if (id === \"\") {\n    const root = registry.namespaces.get(\"\")!\n    const out: RootHelp = {\n      kind: \"root\",\n      namespaces: root.namespaces.map((n) => namespaceSummary(registry, n)),\n      commands: root.commands.map((c) => commandSummary(registry.commands.get(c)!, options)),\n    }\n    if (root.description !== undefined) out.description = root.description\n    return out\n  }\n  const ns = registry.namespaces.get(id)\n  if (ns) {\n    const out: NamespaceHelp = {\n      kind: \"namespace\",\n      id,\n      namespaces: ns.namespaces.map((n) => namespaceSummary(registry, n)),\n      commands: ns.commands.map((c) => commandSummary(registry.commands.get(c)!, options)),\n    }\n    if (ns.description !== undefined) out.description = ns.description\n    const self = registry.commands.get(id)\n    if (self) out.command = commandHelp(self, options)\n    return out\n  }\n  return commandHelp(findCommand(registry, id), options)\n}\n\nfunction namespaceSummary(registry: Registry, id: string): HelpNamespaceSummary {\n  const description = registry.namespaces.get(id)?.description\n  const first = description?.split(\"\\n\").find((l) => l.trim() !== \"\")\n  return first === undefined ? { id } : { id, description: first.replace(/^#+\\s*/, \"\").trim() }\n}\n\nfunction commandSummary(entry: RegisteredCommand, options: HelpOptions): HelpCommandSummary {\n  const c = entry.command\n  const out: HelpCommandSummary = {\n    id: entry.id,\n    description: c.description,\n    readOnly: c.readOnly,\n    destructive: c.destructive,\n    requiresConfirmation: c.requiresConfirmation,\n  }\n  if (c.needsApproval !== undefined) out.needsApproval = \"conditional\"\n  const tool = options.toolFor?.(entry)\n  if (tool !== undefined) out.tool = tool\n  return out\n}\n\nfunction commandHelp(entry: RegisteredCommand, options: HelpOptions): CommandHelp {\n  const { file: _file, ...meta } = describeCommand(entry)\n  const c = entry.command\n  const errors = [\"INVALID_ARGUMENT\"]\n  if (!c.readOnly || c.scopes.length > 0) errors.push(\"UNAUTHENTICATED\", \"PERMISSION_DENIED\")\n  // 승인 (항상 · 조건식) = ask 방식의 확인 오류. APPROVAL_REQUIRED 는 표면 설정 · 행위자에 따라 승인 명령어 모두에서 가능 (§4 승인)\n  if (c.requiresConfirmation || c.needsApproval !== undefined) errors.push(\"INPUT_UNAVAILABLE\", \"INPUT_DECLINED\")\n  const out: CommandHelp = { kind: \"command\", ...meta, errors }\n  const tool = options.toolFor?.(entry)\n  if (tool !== undefined) out.tool = tool\n  return out\n}\n\n/** help 의 사람용 텍스트 (MCP text content). 구조는 structuredContent 가 원본 */\nexport function formatHelp(value: Help, call = \"execute\"): string {\n  const lines: string[] = []\n  const hint = (target: string) => `${call}({ command: \"help\", args: { target: \"${target}\" } })`\n  const listCommands = (commands: HelpCommandSummary[]) => {\n    if (commands.length === 0) return\n    lines.push(\"Commands:\")\n    const width = Math.max(...commands.map((c) => c.id.length))\n    for (const c of commands) {\n      const flags = safetyFlags(c)\n      const via = c.tool !== undefined ? ` (via ${c.tool})` : \"\"\n      lines.push(`  ${c.id.padEnd(width)}  ${c.description}${flags ? ` [${flags}]` : \"\"}${via}`)\n    }\n  }\n  const listNamespaces = (namespaces: HelpNamespaceSummary[]) => {\n    if (namespaces.length === 0) return\n    lines.push(\"Namespaces:\")\n    const width = Math.max(...namespaces.map((n) => n.id.length))\n    for (const n of namespaces) lines.push(`  ${n.id.padEnd(width)}  ${n.description ?? \"\"}`.trimEnd())\n  }\n\n  if (value.kind === \"command\") {\n    lines.push(`${value.id}: ${value.description}`)\n    if (value.aliases.length > 0) lines.push(`Aliases: ${value.aliases.join(\", \")}`)\n    const flags = safetyFlags(value)\n    lines.push(`Safety: ${flags || \"none\"}`)\n    if (value.scopes.length > 0) lines.push(`Scopes: ${value.scopes.join(\", \")}`)\n    if (value.tool !== undefined) lines.push(`Tool: ${value.tool}`)\n    lines.push(\"Input schema:\", JSON.stringify(value.inputSchema, null, 2))\n    if (value.examples.length > 0) {\n      lines.push(\"Examples:\")\n      for (const e of value.examples) lines.push(`  ${JSON.stringify(e)}`)\n    }\n    lines.push(`Errors: ${value.errors.join(\", \")}`)\n    return lines.join(\"\\n\")\n  }\n\n  if (value.kind === \"namespace\") lines.push(value.id)\n  if (value.description !== undefined) lines.push(value.description, \"\")\n  listNamespaces(value.namespaces)\n  listCommands(value.commands)\n  if (value.kind === \"namespace\" && value.command !== undefined) {\n    lines.push(\"\", formatHelp(value.command, call))\n  }\n  lines.push(\"\", `Details: ${hint(value.kind === \"root\" ? \"<namespace or command>\" : `${value.id}.<command>`)}`)\n  return lines.join(\"\\n\").replace(/^\\n+/, \"\")\n}\n\nfunction safetyFlags(c: { readOnly: boolean; destructive: boolean; requiresConfirmation: boolean; needsApproval?: \"conditional\" }): string {\n  const flags: string[] = []\n  if (c.readOnly) flags.push(\"read-only\")\n  if (c.destructive) flags.push(\"destructive\")\n  if (c.requiresConfirmation) flags.push(\"requires confirmation\")\n  else if (c.needsApproval !== undefined) flags.push(\"may require confirmation\")\n  return flags.join(\", \")\n}\n"]}

package/dist/mcp/host.d.ts

@@ -0,0 +1,14 @@
+/**
+ * loopback 판정 · Host 허용 목록 (§6 보안). mcp/http.ts (Origin · Host 검사) · config.ts (allowedHosts 형식 검사) 가 공유.
+ * Node 내장 모듈 · SDK import 없음
+ */
+export declare const LOOPBACK_HOSTNAMES: ReadonlySet<string>;
+/** allowedOrigins · allowedHosts 의 loopback 항목 */
+export declare const LOOPBACK_ENTRY = "loopback";
+/** allowedHosts 항목 형식 문제. 없으면 undefined (config 검사) */
+export declare function allowedHostProblem(entry: unknown): string | undefined;
+/**
+ * Host 허용 여부 (server.allowedHosts). "*" = 전체, "loopback" = loopback 호스트 (포트 무관),
+ * 포트 없는 항목 = 그 호스트의 모든 포트, 포트 있는 항목 = 그 포트만. 대소문자 · 끝 "." 무시. 형식 오류 = false
+ */
+export declare function hostAllowed(host: string, allowed: readonly string[]): boolean;

package/dist/mcp/host.js

@@ -0,0 +1,48 @@
+/**
+ * loopback 판정 · Host 허용 목록 (§6 보안). mcp/http.ts (Origin · Host 검사) · config.ts (allowedHosts 형식 검사) 가 공유.
+ * Node 내장 모듈 · SDK import 없음
+ */
+export const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** allowedOrigins · allowedHosts 의 loopback 항목 */
+export const LOOPBACK_ENTRY = "loopback";
+/** Host 값 → 소문자 hostname (끝 "." 제거) · port (없으면 ""). 형식 오류 = undefined */
+function parseHost(value) {
+    if (value === "" || /[\s/?#@\\]/.test(value))
+        return undefined;
+    let url;
+    try {
+        url = new URL(`http://${value}`);
+    }
+    catch {
+        return undefined;
+    }
+    // URL 이 기본 포트 (80) 를 지우므로 원문의 포트를 쓴다
+    const port = /:(\d+)$/.exec(value)?.[1] ?? "";
+    return { hostname: url.hostname.replace(/\.$/, ""), port };
+}
+/** allowedHosts 항목 형식 문제. 없으면 undefined (config 검사) */
+export function allowedHostProblem(entry) {
+    if (entry === "*" || entry === LOOPBACK_ENTRY)
+        return undefined;
+    if (typeof entry !== "string" || parseHost(entry) === undefined)
+        return `invalid host ${JSON.stringify(entry)}`;
+    return undefined;
+}
+/**
+ * Host 허용 여부 (server.allowedHosts). "*" = 전체, "loopback" = loopback 호스트 (포트 무관),
+ * 포트 없는 항목 = 그 호스트의 모든 포트, 포트 있는 항목 = 그 포트만. 대소문자 · 끝 "." 무시. 형식 오류 = false
+ */
+export function hostAllowed(host, allowed) {
+    if (allowed.includes("*"))
+        return true;
+    const actual = parseHost(host);
+    if (actual === undefined)
+        return false;
+    if (LOOPBACK_HOSTNAMES.has(actual.hostname) && allowed.includes(LOOPBACK_ENTRY))
+        return true;
+    return allowed.some((entry) => {
+        const expected = entry === LOOPBACK_ENTRY ? undefined : parseHost(entry);
+        return expected !== undefined && expected.hostname === actual.hostname && (expected.port === "" || expected.port === actual.port);
+    });
+}
+//# sourceMappingURL=host.js.map

package/dist/mcp/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/mcp/host.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAA;AAEnG,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAA;AAExC,0EAA0E;AAC1E,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,KAAK,KAAK,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAC9D,IAAI,GAAQ,CAAA;IACZ,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,KAAK,EAAE,CAAC,CAAA;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,qCAAqC;IACrC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC7C,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAA;AAC5D,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,cAAc;QAAE,OAAO,SAAS,CAAA;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,OAAO,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/G,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,OAA0B;IAClE,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC9B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACtC,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5F,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QAC5B,MAAM,QAAQ,GAAG,KAAK,KAAK,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QACxE,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,EAAE,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,CAAA;IACnI,CAAC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["/**\n * loopback 판정 · Host 허용 목록 (§6 보안). mcp/http.ts (Origin · Host 검사) · config.ts (allowedHosts 형식 검사) 가 공유.\n * Node 내장 모듈 · SDK import 없음\n */\n\nexport const LOOPBACK_HOSTNAMES: ReadonlySet<string> = new Set([\"localhost\", \"127.0.0.1\", \"[::1]\"])\n\n/** allowedOrigins · allowedHosts 의 loopback 항목 */\nexport const LOOPBACK_ENTRY = \"loopback\"\n\n/** Host 값 → 소문자 hostname (끝 \".\" 제거) · port (없으면 \"\"). 형식 오류 = undefined */\nfunction parseHost(value: string): { hostname: string; port: string } | undefined {\n  if (value === \"\" || /[\\s/?#@\\\\]/.test(value)) return undefined\n  let url: URL\n  try {\n    url = new URL(`http://${value}`)\n  } catch {\n    return undefined\n  }\n  // URL 이 기본 포트 (80) 를 지우므로 원문의 포트를 쓴다\n  const port = /:(\\d+)$/.exec(value)?.[1] ?? \"\"\n  return { hostname: url.hostname.replace(/\\.$/, \"\"), port }\n}\n\n/** allowedHosts 항목 형식 문제. 없으면 undefined (config 검사) */\nexport function allowedHostProblem(entry: unknown): string | undefined {\n  if (entry === \"*\" || entry === LOOPBACK_ENTRY) return undefined\n  if (typeof entry !== \"string\" || parseHost(entry) === undefined) return `invalid host ${JSON.stringify(entry)}`\n  return undefined\n}\n\n/**\n * Host 허용 여부 (server.allowedHosts). \"*\" = 전체, \"loopback\" = loopback 호스트 (포트 무관),\n * 포트 없는 항목 = 그 호스트의 모든 포트, 포트 있는 항목 = 그 포트만. 대소문자 · 끝 \".\" 무시. 형식 오류 = false\n */\nexport function hostAllowed(host: string, allowed: readonly string[]): boolean {\n  if (allowed.includes(\"*\")) return true\n  const actual = parseHost(host)\n  if (actual === undefined) return false\n  if (LOOPBACK_HOSTNAMES.has(actual.hostname) && allowed.includes(LOOPBACK_ENTRY)) return true\n  return allowed.some((entry) => {\n    const expected = entry === LOOPBACK_ENTRY ? undefined : parseHost(entry)\n    return expected !== undefined && expected.hostname === actual.hostname && (expected.port === \"\" || expected.port === actual.port)\n  })\n}\n"]}

package/dist/mcp/http.d.ts

@@ -1,17 +1,29 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { MextApp } from "../command.ts";
+import { type BuiltinSurface, type ReportedClient } from "../caller.ts";
 import { type Principal } from "../principal.ts";
 import type { Registry } from "../registry.ts";
-import { type RouteEntry } from "../route.ts";
+import { type RouteEntry, type RouteMethod, type RouteOptions } from "../route.ts";
+import { MAX_BODY_BYTES } from "./constants.ts";
 import type { Instrumentation } from "../instrumentation.ts";
 import type { ToolExposure } from "./dispatch.ts";
 import { type McpCoreOptions } from "./server.ts";
 import type { MextState } from "../state.ts";
-/** 요청 본문 상한 (SDK 기본과 같음) */
-export declare const MAX_BODY_BYTES: number;
+export { MAX_BODY_BYTES };
 export interface McpAuthRequest {
     /** Authorization 헤더 원문 */
     authorization: string | undefined;
+    /** 요청 헤더 (세션 쿠키 · 프록시가 붙인 헤더). 복사본 */
+    headers: Headers;
+    /** 어댑터 기본 표면. POST /mcp = "mcp". 반환 Principal.surface 로 논리 표면을 바꿀 수 있다 */
+    surface: BuiltinSurface;
+    /** 요청 _meta 의 clientInfo (2026-07-28). 자가 신고 값: 주체 · 행위자 · 표면 판정에 쓰지 않는다 */
+    client: ReportedClient | undefined;
+    /** routes/ 요청 (export auth, §12.4) 만. method = 요청 메서드 (HEAD = GET), path = route 파일 패턴 ("/items/[id]"). POST /mcp = 없음 */
+    route?: {
+        method: RouteMethod;
+        path: string;
+    };
 }
 export interface McpHttpOptions {
     registry: Registry;
@@ -28,10 +40,17 @@ export interface McpHttpOptions {
         /** 기본 3100. 0 = 임의 포트 */
         port?: number;
         /**
-         * Origin 허용 목록 (https://app.example.com 형식, "*" = 전체).
+         * Origin 허용 목록 (https://app.example.com · chrome-extension://<id> 형식, "*" = 전체, "loopback" = loopback).
          * 미지정 = loopback (localhost · 127.0.0.1 · [::1], 포트 무관) 만. Origin 헤더 없는 요청은 항상 통과
          */
         allowedOrigins?: string[];
+        /**
+         * Host 허용 목록 (api.example.com = 모든 포트 · api.example.com:8443 = 그 포트만, "loopback" = loopback, "*" = 전체).
+         * 미지정 = 검사 없음. 지정 = 목록 밖 Host 의 모든 요청 (/mcp · routes · well-known) = 403 (DNS rebinding 방어)
+         */
+        allowedHosts?: string[];
+        /** POST /mcp 본문 상한 (바이트). 기본 MAX_BODY_BYTES (4 MiB). 넘으면 413. route 의 export maxBodyBytes = true 도 이 값 */
+        maxBodyBytes?: number;
     };
     /** serverInfo.name · 안내 문구. 기본 "mext" */
     name?: string;
@@ -55,14 +74,23 @@ export interface McpHttpOptions {
      * 클라이언트 (mext login · MCP 클라이언트) 가 인가 서버를 찾는 데 쓴다
      */
     oauth?: OAuthResourceOptions;
-    /** routes/ (§12.4). MCP 엔드포인트 밖 경로. Origin 검사 · auth 없음. ctx.app = MCP 와 같은 인스턴스 */
+    /**
+     * routes/ (§12.4). MCP 엔드포인트 밖 경로. ctx.app = MCP 와 같은 인스턴스.
+     * Origin 검사 · auth = 기본 없음. 모듈의 export origin · auth (없으면 routeDefaults) 가 있으면 allowedOrigins · auth 를 /mcp 와 같은 규칙으로
+     */
     routes?: readonly RouteEntry[];
+    /** 설정 routes (§12.4): 모든 route 의 auth · origin · maxBodyBytes 기본값. 모듈 export 가 덮어쓴다 */
+    routeDefaults?: RouteOptions;
     /** 주입 state (§12.1). 자원 구독 · ctx.resourceUpdated (§12.5) */
     state?: MextState;
     /** McpCoreOptions.taskTiming (테스트) */
     taskTiming?: McpCoreOptions["taskTiming"];
     /** McpCoreOptions.taskExecution. handler.js = "waitUntil" */
     taskExecution?: McpCoreOptions["taskExecution"];
+    /** 감사 (config.audit, §11.1) */
+    audit?: McpCoreOptions["audit"];
+    /** 승인의 표면별 확인 방식 (config.approval, §4 승인) */
+    approval?: McpCoreOptions["approval"];
 }
 /** fetch 의 두 번째 인자. waitUntil = 응답 후 실행 유지 (handler.js 플랫폼, tasks §10) */
 export interface McpFetchContext {
@@ -94,7 +122,7 @@ export interface McpFetchHandler {
 }
 /**
  * Streamable HTTP (2026-07-28) 의 transport 무관 처리 (Web Request → Response).
- * 순서: 경로 (routes · 404) → Origin (403) → 메서드 (POST 외 405) → 본문 (413) → auth (401) → SDK createMcpHandler.
+ * 순서: Host (allowedHosts, 모든 경로 403) → 경로 (routes · 404) → Origin (403) → 메서드 (POST 외 405) → 본문 (413) → auth (401) → SDK createMcpHandler.
  * SDK 가 요청별 버전 · 헤더 검증 (-32020) · server/discover · Mcp-Param-Command · 2025 레거시 stateless 를 처리.
  * progressToken 있는 2026-07-28 요청 = SSE 응답 (진행률 알림), 그 외 = JSON.
  */
@@ -110,5 +138,8 @@ export interface McpHttpServer {
 }
 /** createMcpHttpHandler + node:http listen. 기본 127.0.0.1:3100 */
 export declare function startMcpHttpServer(options: McpHttpOptions): Promise<McpHttpServer>;
-/** Origin 허용 여부. allowed 미지정 = loopback 만, 지정 = 목록의 origin 과 정확히 일치 ("*" = 전체) */
+/**
+ * Origin 허용 여부. allowed 미지정 = loopback 만, 지정 = 목록의 origin 과 정확히 일치 ("*" = 전체, "loopback" = loopback).
+ * http · https 외 scheme (chrome-extension://<id>) = URL.origin 이 "null" 이라 목록과 문자열 비교
+ */
 export declare function originAllowed(origin: string, allowed: readonly string[] | undefined): boolean;

package/dist/mcp/http.js

@@ -1,20 +1,22 @@
 import { createServer } from "node:http";
-import { Readable } from "node:stream";
-import { createMcpHandler, InMemoryServerEventBus, isLegacyRequest } from "@modelcontextprotocol/server";
-import { isMextError } from "../errors.js";
-import { ANONYMOUS } from "../principal.js";
+import { CLIENT_INFO_META_KEY, createMcpHandler, InMemoryServerEventBus, isLegacyRequest } from "@modelcontextprotocol/server";
+import { auditHidden } from "../audit.js";
+import { isMextError, unauthenticated } from "../errors.js";
+import { defaultSurface, reportedClient, surfaceOf } from "../caller.js";
+import { exposedRegistry } from "../expose.js";
+import { ANONYMOUS, assertCallerFields } from "../principal.js";
 import { createRouteDispatcher, onceApp } from "../route.js";
-import { DEFAULT_HOST, DEFAULT_PORT, MCP_PATH } from "./constants.js";
+import { DEFAULT_HOST, DEFAULT_PORT, MAX_BODY_BYTES, MCP_PATH } from "./constants.js";
+import { hostAllowed, LOOPBACK_ENTRY, LOOPBACK_HOSTNAMES } from "./host.js";
 import { createMcpServerFactory, principalAuthInfo } from "./server.js";
 import { bridgeResourceUpdates, narrowListenRequest, resourceUpdatedFn, trackBody } from "./subscriptions.js";
 import { hasTaskCommands, requestsTask } from "./tasks.js";
-/** 요청 본문 상한 (SDK 기본과 같음) */
-export const MAX_BODY_BYTES = 4 * 1024 * 1024;
+export { MAX_BODY_BYTES };
 /** RFC 9728 well-known 경로 */
 export const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
 /**
  * Streamable HTTP (2026-07-28) 의 transport 무관 처리 (Web Request → Response).
- * 순서: 경로 (routes · 404) → Origin (403) → 메서드 (POST 외 405) → 본문 (413) → auth (401) → SDK createMcpHandler.
+ * 순서: Host (allowedHosts, 모든 경로 403) → 경로 (routes · 404) → Origin (403) → 메서드 (POST 외 405) → 본문 (413) → auth (401) → SDK createMcpHandler.
  * SDK 가 요청별 버전 · 헤더 검증 (-32020) · server/discover · Mcp-Param-Command · 2025 레거시 stateless 를 처리.
  * progressToken 있는 2026-07-28 요청 = SSE 응답 (진행률 알림), 그 외 = JSON.
  */
@@ -22,8 +24,17 @@ export function createMcpFetchHandler(options) {
     // ctx.app = 프로세스당 1회. 명령어 · route 가 공유
     const app = options.app ? onceApp(options.app) : undefined;
     const resourceUpdated = resourceUpdatedFn(options.state);
+    const report = reporter(options.onerror);
+    const allowedOrigins = options.server?.allowedOrigins;
     const routes = options.routes?.length
-        ? createRouteDispatcher({ routes: options.routes, app: onceApp(app), resourceUpdated })
+        ? createRouteDispatcher({
+            routes: options.routes,
+            app: onceApp(app),
+            resourceUpdated,
+            guard: routeGuard(options, report),
+            maxBodyBytes: options.server?.maxBodyBytes ?? MAX_BODY_BYTES,
+            ...(options.routeDefaults ? { defaults: options.routeDefaults } : {}),
+        })
         : undefined;
     const factory = createMcpServerFactory({
         registry: options.registry,
@@ -39,11 +50,13 @@ export function createMcpFetchHandler(options) {
         ...(options.state ? { state: options.state } : {}),
         ...(options.taskTiming ? { taskTiming: options.taskTiming } : {}),
         ...(options.taskExecution ? { taskExecution: options.taskExecution } : {}),
+        ...(options.audit ? { audit: options.audit } : {}),
+        ...(options.approval ? { approval: options.approval } : {}),
         transport: "http",
     });
     const tasks = options.state?.store !== undefined && hasTaskCommands(options.registry);
-    const report = reporter(options.onerror);
-    const sdkOptions = options.onerror ? { onerror: report } : {};
+    const maxBodyBytes = options.server?.maxBodyBytes ?? MAX_BODY_BYTES;
+    const sdkOptions = { ...(options.onerror ? { onerror: report } : {}), maxRequestBodySize: maxBodyBytes };
     // subscriptions/listen (§12.5) = 전용 SDK handler (ack · 15초 keepalive · 완료 result). 갱신 = state 허브 → SDK bus
     const listenBus = new InMemoryServerEventBus(report);
     const subscriptions = { state: options.state, resources: options.registry.resources };
@@ -54,9 +67,19 @@ export function createMcpFetchHandler(options) {
     // 진행률 없는 요청 = JSON (auto: 관련 메시지가 없으면 단일 JSON), 진행률 있는 요청 = SSE
     const jsonHandler = createMcpHandler(factory, { ...sdkOptions, responseMode: "auto" });
     const sseHandler = createMcpHandler(factory, { ...sdkOptions, responseMode: "sse" });
-    const allowedOrigins = options.server?.allowedOrigins;
+    const allowedHosts = options.server?.allowedHosts;
     const handle = async (request, context) => {
         const url = new URL(request.url);
+        if (allowedHosts !== undefined) {
+            const host = request.headers.get("host") ?? url.host;
+            if (!hostAllowed(host, allowedHosts)) {
+                await request.body?.cancel().catch(() => { });
+                const message = `Forbidden: host ${host} is not allowed.`;
+                if (url.pathname === MCP_PATH)
+                    return jsonResponse(403, rpcError(-32_000, message));
+                return jsonResponse(403, { error: { code: "REQUEST_REJECTED", message, reason: "host" } });
+            }
+        }
         const oauth = options.oauth;
         if (oauth && (url.pathname === PROTECTED_RESOURCE_METADATA_PATH || url.pathname === protectedResourceMetadataPath())) {
             if (request.method !== "GET")
@@ -77,7 +100,7 @@ export function createMcpFetchHandler(options) {
         if (request.method !== "POST") {
             return jsonResponse(405, rpcError(-32_000, "Method not allowed."), { Allow: "POST" });
         }
-        const body = await readBody(request.body, MAX_BODY_BYTES);
+        const body = await readBody(request.body, maxBodyBytes);
         if (body === "too-large")
             return jsonResponse(413, rpcError(-32_000, "Request body too large."));
         const parsed = parseJson(body);
@@ -85,7 +108,14 @@ export function createMcpFetchHandler(options) {
         let principal = ANONYMOUS;
         if (options.auth) {
             try {
-                principal = await options.auth({ authorization: request.headers.get("authorization") ?? undefined });
+                principal = await options.auth({
+                    authorization: request.headers.get("authorization") ?? undefined,
+                    headers: new Headers(request.headers),
+                    surface: defaultSurface("http"),
+                    client: reportedClientOf(parsed),
+                });
+                // actor · surface 형식 오류 = auth 예외와 같음 (500 + onerror)
+                assertCallerFields(principal, "auth");
             }
             catch (error) {
                 if (isMextError(error, "UNAUTHENTICATED")) {
@@ -103,7 +133,7 @@ export function createMcpFetchHandler(options) {
         });
         const parsedBody = parsed === NOT_JSON ? undefined : parsed;
         // 2025-11-25 이하 (envelope 없음) = SDK stateless 레거시 경로. 진행률 기반 SSE 전환은 2026-07-28 요청만
-        const legacy = await isLegacyRequest(sdkRequest, parsedBody, { maxRequestBodySize: MAX_BODY_BYTES });
+        const legacy = await isLegacyRequest(sdkRequest, parsedBody, { maxRequestBodySize: maxBodyBytes });
         const listen = legacy ? undefined : narrowListenRequest(parsedBody, subscriptions, principal);
         if (listen !== undefined) {
             const { response, done } = trackBody(await listenHandler.fetch(sdkRequest, { authInfo: principalAuthInfo(principal), parsedBody: listen }));
@@ -111,8 +141,24 @@ export function createMcpFetchHandler(options) {
             void done.then(() => listenBodies.delete(done));
             return response;
         }
+        // tools: "command" 의 숨긴 명령어 호출 = SDK 가 등록되지 않은 도구로 거부해 mext 콜백이 없다 → 본문을 넘기기 전에 기록
+        // (§11.1 includeHidden). 응답은 그대로 SDK 가 만들고, 전달은 기다리지 않는다
+        if (options.audit?.includeHidden === true && options.tools === "command") {
+            const hidden = hiddenToolCall(options.registry, principal, parsedBody);
+            const work = hidden &&
+                auditHidden(hidden, {
+                    audit: options.audit,
+                    principal,
+                    transport: "http",
+                    ...optional("client", reportedClientOf(parsedBody)),
+                    ...optional("traceContext", metaOf(parsedBody)),
+                });
+            if (work)
+                context?.waitUntil?.(work);
+        }
         // task 가 될 수 있는 tools/call = application/json (CreateTaskResult, §12.6)
-        const sse = !legacy && hasProgressToken(parsedBody) && !(tasks && requestsTask(options.registry, parsedBody));
+        // 대상 판정 = 주체의 표면에서 보이는 명령어 (숨긴 task 명령어는 없는 명령어와 같은 응답 형식, §4 expose)
+        const sse = !legacy && hasProgressToken(parsedBody) && !(tasks && requestsTask(exposedRegistry(options.registry, surfaceOf(principal, "http")), parsedBody));
         const handler = sse ? sseHandler : jsonHandler;
         return handler.fetch(sdkRequest, {
             authInfo: principalAuthInfo(principal, context?.waitUntil),
@@ -168,7 +214,7 @@ export function createMcpHttpHandler(options) {
         const request = new Request(requestUrl(req), {
             method: req.method ?? "GET",
             headers: nodeHeaders(req),
-            ...(hasBody ? { body: Readable.toWeb(req), duplex: "half" } : {}),
+            ...(hasBody ? { body: nodeBody(req), duplex: "half" } : {}),
             signal: controller.signal,
         });
         core
@@ -205,6 +251,56 @@ function reporter(onerror) {
         }
     };
 }
+/**
+ * routes/ 의 export origin · auth 판정 (§12.4). /mcp 와 같은 allowedOrigins · auth · WWW-Authenticate.
+ * 본문 = { error: { code, message, ...details } } (specs/http.md §3.3 오류 본문 모양)
+ */
+function routeGuard(options, report) {
+    const warned = new Set();
+    const challenge = (error, request) => {
+        const metadata = options.oauth ? resourceMetadataUrl(options.oauth, new URL(request.url)) : undefined;
+        return jsonResponse(401, { error: error.toJSON() }, { "WWW-Authenticate": bearerChallenge(error, metadata) });
+    };
+    return {
+        origin(request) {
+            const origin = request.headers.get("origin") ?? undefined;
+            if (origin === undefined || origin === "" || originAllowed(origin, options.server?.allowedOrigins))
+                return undefined;
+            return jsonResponse(403, { error: { code: "REQUEST_REJECTED", message: `Forbidden: origin ${origin} is not allowed.`, reason: "origin" } });
+        },
+        async authenticate(request, mode, route) {
+            if (!options.auth) {
+                if (mode === "optional")
+                    return ANONYMOUS;
+                if (!warned.has(route.path)) {
+                    warned.add(route.path);
+                    report(new Error(`route ${route.path}: auth = true (export auth or routes.auth) but mext.config.ts has no auth. Every request is 401`));
+                }
+                return challenge(unauthenticated("missing_token"), request);
+            }
+            let principal;
+            try {
+                principal = await options.auth({
+                    authorization: request.headers.get("authorization") ?? undefined,
+                    headers: new Headers(request.headers),
+                    surface: defaultSurface("http"),
+                    client: undefined,
+                    route,
+                });
+                assertCallerFields(principal, "auth");
+            }
+            catch (error) {
+                if (isMextError(error, "UNAUTHENTICATED"))
+                    return challenge(error, request);
+                report(error);
+                return new Response("Internal Server Error\n", { status: 500, headers: { "Content-Type": "text/plain; charset=utf-8" } });
+            }
+            if (mode === true && principal.kind === "anonymous")
+                return challenge(unauthenticated("missing_token"), request);
+            return principal;
+        },
+    };
+}
 /** createMcpHttpHandler + node:http listen. 기본 127.0.0.1:3100 */
 export async function startMcpHttpServer(options) {
     const listener = createMcpHttpHandler(options);
@@ -231,8 +327,10 @@ export async function startMcpHttpServer(options) {
     };
 }
 /* Origin */
-const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
-/** Origin 허용 여부. allowed 미지정 = loopback 만, 지정 = 목록의 origin 과 정확히 일치 ("*" = 전체) */
+/**
+ * Origin 허용 여부. allowed 미지정 = loopback 만, 지정 = 목록의 origin 과 정확히 일치 ("*" = 전체, "loopback" = loopback).
+ * http · https 외 scheme (chrome-extension://<id>) = URL.origin 이 "null" 이라 목록과 문자열 비교
+ */
 export function originAllowed(origin, allowed) {
     if (allowed?.includes("*"))
         return true;
@@ -244,9 +342,11 @@ export function originAllowed(origin, allowed) {
         return false;
     }
     if (url.protocol !== "http:" && url.protocol !== "https:")
-        return false;
+        return allowed?.includes(origin) ?? false;
+    if (LOOPBACK_HOSTNAMES.has(url.hostname) && (allowed === undefined || allowed.includes(LOOPBACK_ENTRY)))
+        return true;
     if (allowed === undefined)
-        return LOOPBACK_HOSTNAMES.has(url.hostname);
+        return false;
     return allowed.some((entry) => normalizeOrigin(entry) === url.origin);
 }
 function normalizeOrigin(entry) {
@@ -266,6 +366,45 @@ function statelessHeaders(source) {
         headers.delete(name);
     return headers;
 }
+/**
+ * IncomingMessage → 요청 본문 스트림 (backpressure = pause · resume).
+ * Readable.toWeb 대신 직접: Node 22 의 toWeb 스트림은 cancel (413 · 403 조기 거부) 뒤 남은 본문이 도착하면
+ * 닫힌 controller 에 enqueue 해 프로세스가 죽는다 (ERR_INVALID_STATE). cancel = 남은 본문 버림 (Node 기본 동작과 같음)
+ */
+function nodeBody(req) {
+    let done = false;
+    return new ReadableStream({
+        start(controller) {
+            req.on("data", (chunk) => {
+                if (done)
+                    return;
+                controller.enqueue(new Uint8Array(chunk));
+                if ((controller.desiredSize ?? 0) <= 0)
+                    req.pause();
+            });
+            req.once("end", () => {
+                if (done)
+                    return;
+                done = true;
+                controller.close();
+            });
+            req.once("error", (error) => {
+                if (done)
+                    return;
+                done = true;
+                controller.error(error);
+            });
+            req.pause();
+        },
+        pull() {
+            req.resume();
+        },
+        cancel() {
+            done = true;
+            req.resume();
+        },
+    });
+}
 function nodeHeaders(req) {
     const headers = new Headers();
     for (const [name, value] of Object.entries(req.headers)) {
@@ -358,13 +497,16 @@ function jsonResponse(status, body, headers = {}) {
     return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", ...headers } });
 }
 function unauthenticatedResponse(error, id, resourceMetadata) {
+    return jsonResponse(401, rpcError(-32_001, error.message, error.toJSON(), id), { "WWW-Authenticate": bearerChallenge(error, resourceMetadata) });
+}
+/** 401 의 WWW-Authenticate (/mcp · routes 공통) */
+function bearerChallenge(error, resourceMetadata) {
     const params = [];
     if (error.details.reason === "invalid_token")
         params.push('error="invalid_token"');
     if (resourceMetadata !== undefined)
         params.push(`resource_metadata="${resourceMetadata}"`);
-    const challenge = params.length > 0 ? `Bearer ${params.join(", ")}` : "Bearer";
-    return jsonResponse(401, rpcError(-32_001, error.message, error.toJSON(), id), { "WWW-Authenticate": challenge });
+    return params.length > 0 ? `Bearer ${params.join(", ")}` : "Bearer";
 }
 /* OAuth 보호 자원 메타데이터 (RFC 9728) */
 /** MCP 엔드포인트 경로를 삽입한 well-known 경로 (/.well-known/oauth-protected-resource/mcp) */
@@ -411,6 +553,40 @@ function requestId(body) {
         return null;
     return typeof id === "string" || typeof id === "number" ? id : null;
 }
+/** 요청 본문 params._meta 의 clientInfo (2026-07-28 envelope). 자가 신고 값. 없음 · 형식 오류 = undefined */
+function reportedClientOf(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const meta = body.params?._meta;
+    if (meta === null || typeof meta !== "object")
+        return undefined;
+    return reportedClient(meta[CLIENT_INFO_META_KEY]);
+}
+/** tools/call 의 params._meta (traceparent 등) */
+function metaOf(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const meta = body.params?._meta;
+    return meta !== null && typeof meta === "object" && !Array.isArray(meta) ? meta : undefined;
+}
+function optional(key, value) {
+    return (value === undefined ? {} : { [key]: value });
+}
+/**
+ * tools: "command" 의 tools/call 이 가리키는 명령어가 주체의 표면에서 숨긴 명령어면 그 항목. 도구 이름 = 정식 ID 만 (별칭은 도구가 아니다).
+ * 보이는 명령어 · 없는 이름 = undefined
+ */
+function hiddenToolCall(registry, principal, body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const { method, params } = body;
+    if (method !== "tools/call" || typeof params?.name !== "string")
+        return undefined;
+    const entry = registry.commands.get(params.name);
+    if (!entry)
+        return undefined;
+    return exposedRegistry(registry, surfaceOf(principal, "http")).commands.has(entry.id) ? undefined : entry;
+}
 function hasProgressToken(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return false;