@humain/terminal 0.0.6 → 0.0.7

package/dist/humain/mcp-adapter/vendor/mcp-oauth-provider.ts

@@ -8,6 +8,7 @@
 import {
   UnauthorizedError,
   type AddClientAuthentication,
+  type OAuthClientInformationContext,
   type OAuthClientProvider,
   type OAuthDiscoveryState,
 } from "@modelcontextprotocol/client"
@@ -21,14 +22,14 @@ import {
   updateTokens,
   updateClientInfo,
   clearAllCredentials,
-  clearClientInfo,
   clearCodeVerifier,
-  clearTokens,
+  invalidateAuthEntryCache,
   type AuthEntry,
   type AuthStorageOptions,
   type StoredTokens,
   type StoredClientInfo,
 } from "./mcp-auth.ts"
+import { OAuthMetadataSchema, OpenIdProviderDiscoveryMetadataSchema } from "@modelcontextprotocol/core"
 import { resolveCommandSecret } from "./utils.ts"
 import { getAppClientUri, getAppName } from "./agent-dir.ts"
 
@@ -71,6 +72,18 @@ function issuersMatch(first: string, second: string): boolean {
     || (second.endsWith("/") && second.slice(0, -1) === first)
 }
 
+function toOAuthTokens(tokens: StoredTokens): IssuerBoundTokens {
+  const result: IssuerBoundTokens = {
+    access_token: tokens.accessToken,
+    token_type: "Bearer",
+  }
+  if (tokens.refreshToken !== undefined) result.refresh_token = tokens.refreshToken
+  if (tokens.expiresAt !== undefined) result.expires_in = Math.max(0, Math.floor(tokens.expiresAt - Date.now() / 1000))
+  if (tokens.scope !== undefined) result.scope = tokens.scope
+  if (tokens.issuer !== undefined) result.issuer = tokens.issuer
+  return result
+}
+
 // Callback server configuration
 const DEFAULT_OAUTH_CALLBACK_PORT = 19876
 const DEFAULT_OAUTH_CALLBACK_PATH = "/callback"
@@ -118,6 +131,7 @@ export interface McpOAuthConfig {
   clientName?: string
   clientUri?: string
   logoUri?: string
+  authServerMetadataUrl?: string
   skipIssuerMetadataValidation?: boolean
 }
 
@@ -149,6 +163,85 @@ export interface McpOAuthCallbacks {
   onRedirect: (url: URL) => void | Promise<void>
 }
 
+function inferIssuerFromMetadataUrl(metadataUrl: string): string | undefined {
+  const url = new URL(metadataUrl)
+  const pathname = url.pathname.replace(/\/+$/, "") || "/"
+  const oauthPrefix = "/.well-known/oauth-authorization-server"
+  if (pathname === oauthPrefix || pathname.startsWith(`${oauthPrefix}/`)) {
+    const issuerPath = pathname.slice(oauthPrefix.length) || "/"
+    return new URL(issuerPath, url.origin).toString()
+  }
+
+  const oidcPath = "/.well-known/openid-configuration"
+  if (pathname === oidcPath || pathname.startsWith(`${oidcPath}/`)) {
+    const issuerPath = pathname.slice(oidcPath.length) || "/"
+    return new URL(issuerPath, url.origin).toString()
+  }
+  if (pathname.endsWith(oidcPath)) {
+    const issuerPath = pathname.slice(0, -oidcPath.length) || "/"
+    return new URL(issuerPath, url.origin).toString()
+  }
+  return undefined
+}
+
+function validateConfiguredIssuer(metadataUrl: string, issuer: string, skipIssuerValidation: boolean): void {
+  let parsedIssuer: URL
+  try {
+    parsedIssuer = new URL(issuer)
+  } catch (error) {
+    throw new Error("OAuth authorization-server metadata issuer must be an absolute URL", { cause: error })
+  }
+  if (parsedIssuer.protocol !== "http:" && parsedIssuer.protocol !== "https:") {
+    throw new Error("OAuth authorization-server metadata issuer must use http:// or https://")
+  }
+
+  const expectedIssuer = inferIssuerFromMetadataUrl(metadataUrl)
+  if (skipIssuerValidation) return
+  if (expectedIssuer !== undefined && !issuersMatch(expectedIssuer, issuer)) {
+    throw new Error(
+      `OAuth authorization-server metadata issuer does not match authServerMetadataUrl: expected ${expectedIssuer}`,
+    )
+  }
+  if (expectedIssuer === undefined && !issuersMatch(new URL(metadataUrl).origin, issuer)) {
+    throw new Error(
+      `OAuth authorization-server metadata issuer does not match authServerMetadataUrl origin: expected ${new URL(metadataUrl).origin}`,
+    )
+  }
+}
+
+async function loadConfiguredDiscoveryState(
+  metadataUrl: string,
+  serverUrl: string,
+  skipIssuerValidation: boolean,
+  signal?: AbortSignal,
+): Promise<OAuthDiscoveryState> {
+  const response = await fetch(metadataUrl, {
+    headers: { accept: "application/json" },
+    ...(signal !== undefined ? { signal } : {}),
+  })
+  if (!response.ok) {
+    await response.text().catch(() => {})
+    throw new Error(`OAuth authServerMetadataUrl request failed with HTTP ${response.status}`)
+  }
+
+  const payload = await response.json()
+  const oauthResult = OAuthMetadataSchema.safeParse(payload)
+  const metadata = oauthResult.success
+    ? oauthResult.data
+    : OpenIdProviderDiscoveryMetadataSchema.parse(payload)
+  validateConfiguredIssuer(metadataUrl, metadata.issuer, skipIssuerValidation)
+
+  const resource = new URL(serverUrl)
+  resource.hash = ""
+  return {
+    authorizationServerUrl: metadata.issuer,
+    authorizationServerMetadata: metadata,
+    // The configured AS document is authoritative, so avoid a second PRM
+    // lookup while still binding the token request to the configured resource.
+    resourceMetadata: { resource: resource.toString() },
+  }
+}
+
 /**
  * OAuth provider implementation for MCP servers.
  * Implements the OAuthClientProvider interface from the MCP SDK.
@@ -161,6 +254,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
   private flowDiscoveryState: OAuthDiscoveryState | undefined
   private flowIssuerMismatch = false
   private flowState: string | undefined
+  private invalidatedAccessToken: string | undefined
+  private invalidatedClientId: string | undefined
+  private lastObservedClientId: string | undefined
+  private lastSavedAccessToken: string | undefined
+  private pendingAuthAccessToken: string | undefined
 
   constructor(
     private serverName: string,
@@ -188,6 +286,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
   deactivate(): void {
     this.active = false
+    this.invalidatedAccessToken = undefined
+    this.invalidatedClientId = undefined
+    this.lastObservedClientId = undefined
+    this.lastSavedAccessToken = undefined
+    this.pendingAuthAccessToken = undefined
   }
 
   private assertStoredIssuerBindings(entry: AuthEntry | undefined, issuer: string | undefined): void {
@@ -264,6 +367,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Returns undefined if no client info exists or if the server URL has changed.
    */
   async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    if (this.invalidatedClientId !== undefined) {
+      invalidateAuthEntryCache(this.serverName)
+    }
     const issuer = this.discoveredIssuer
     const stored = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
     this.assertStoredIssuerBindings(stored, issuer)
@@ -298,7 +404,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
     // Keep client registration associated with this in-flight flow even if
     // another runtime writes the shared persistent entry for the same name.
     const clientInfo = this.flowClientInfo ?? stored?.clientInfo
+    if (clientInfo?.clientId === this.invalidatedClientId) return undefined
     if (clientInfo) {
+      this.invalidatedClientId = undefined
       // A stored SEP-2352 issuer stub for a config-pre-registered client
       // (identified by the explicit marker, or by the legacy stub shape of
       // {clientId, issuer} with no registration metadata) is only meaningful
@@ -329,6 +437,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
       }
       // Return all registration metadata and the local issuer extension.
       // This keeps the SDK OAuth view and the stored issuer binding consistent.
+      this.lastObservedClientId = clientInfo.clientId
       return {
         client_id: clientInfo.clientId,
         client_secret: clientInfo.clientSecret,
@@ -380,6 +489,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
       ...(issuer !== undefined ? { issuer } : {}),
     }
     this.flowClientInfo = clientInfo
+    this.invalidatedClientId = undefined
+    this.lastObservedClientId = clientInfo.clientId
     updateClientInfo(this.serverName, clientInfo, this.serverUrl, this.storageOptions)
   }
 
@@ -387,27 +498,28 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Get stored OAuth tokens.
    * Returns undefined if no tokens exist or if the server URL has changed.
    */
-  async tokens(): Promise<OAuthTokens | undefined> {
+  async tokens(ctx?: OAuthClientInformationContext): Promise<OAuthTokens | undefined> {
+    // Once this provider rejects a token, bypass its process-local cache until
+    // another process replaces that token in shared secure storage.
+    if (this.invalidatedAccessToken !== undefined) {
+      invalidateAuthEntryCache(this.serverName)
+    }
+
     // Use getAuthForUrl to validate tokens are for the current server URL.
     const entry = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
-    if (!entry?.tokens) return undefined
+    if (!entry?.tokens || entry.tokens.accessToken === this.invalidatedAccessToken) return undefined
+    this.invalidatedAccessToken = undefined
     const issuer = this.discoveredIssuer
     this.assertStoredIssuerBindings(entry, issuer)
     if (issuer && entry.tokens.issuer === undefined) {
       entry.tokens.issuer = issuer
       updateTokens(this.serverName, entry.tokens, this.serverUrl, this.storageOptions)
     }
+    if (ctx !== undefined) {
+      this.pendingAuthAccessToken = entry.tokens.accessToken
+    }
 
-    return {
-      access_token: entry.tokens.accessToken,
-      token_type: "Bearer",
-      refresh_token: entry.tokens.refreshToken,
-      expires_in: entry.tokens.expiresAt
-        ? Math.max(0, Math.floor(entry.tokens.expiresAt - Date.now() / 1000))
-        : undefined,
-      scope: entry.tokens.scope,
-      ...(entry.tokens.issuer !== undefined ? { issuer: entry.tokens.issuer } : {}),
-    } as IssuerBoundTokens
+    return toOAuthTokens(entry.tokens)
   }
 
   /**
@@ -427,6 +539,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
     }
     this.throwIfInactive()
     updateTokens(this.serverName, storedTokens, this.serverUrl, this.storageOptions)
+    this.invalidatedAccessToken = undefined
+    this.lastSavedAccessToken = storedTokens.accessToken
     // Discovery must survive the browser redirect so the callback can verify
     // the authorization server that minted the code. Once token issuance
     // succeeds, clear it so a later 401 re-reads PRM and can observe an
@@ -492,6 +606,14 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
   async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
     this.throwIfInactive()
+    if (!this.flowDiscoveryState && this.config.authServerMetadataUrl !== undefined) {
+      this.flowDiscoveryState = await loadConfiguredDiscoveryState(
+        this.config.authServerMetadataUrl,
+        this.serverUrl,
+        this.config.skipIssuerMetadataValidation === true,
+        this.runtimeSignal,
+      )
+    }
     return this.flowDiscoveryState ? structuredClone(this.flowDiscoveryState) : undefined
   }
 
@@ -533,14 +655,31 @@ export class McpOAuthProvider implements OAuthClientProvider {
         this.flowDiscoveryState = undefined
         this.flowIssuerMismatch = false
         this.flowState = undefined
+        this.invalidatedAccessToken = undefined
+        this.invalidatedClientId = undefined
+        this.lastObservedClientId = undefined
+        this.lastSavedAccessToken = undefined
+        this.pendingAuthAccessToken = undefined
         clearAllCredentials(this.serverName, this.storageOptions)
         break
       case "client":
+        // Dynamic client registrations share the same credential-store entry as
+        // tokens. Keep SDK invalidation local so a stale process cannot rewrite
+        // that entry over credentials another process just authorized.
+        this.invalidatedClientId = this.lastObservedClientId
+        this.lastObservedClientId = undefined
         this.flowClientInfo = undefined
-        clearClientInfo(this.serverName, this.storageOptions)
+        invalidateAuthEntryCache(this.serverName)
         break
       case "tokens":
-        clearTokens(this.serverName, this.storageOptions)
+        // Invalidation is provider-local. Persistently deleting a shared token
+        // here lets a process refreshing stale cached credentials erase a token
+        // that another process just authorized. A later tokens() call bypasses
+        // the local cache and adopts a replacement token when one exists.
+        this.invalidatedAccessToken = this.pendingAuthAccessToken ?? this.lastSavedAccessToken
+        this.lastSavedAccessToken = undefined
+        this.pendingAuthAccessToken = undefined
+        invalidateAuthEntryCache(this.serverName)
         break
       case "verifier":
         clearCodeVerifier(this.serverName, this.storageOptions)

package/dist/humain/mcp-adapter/vendor/mcp-output-guard.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { ContentBlock, McpSettings } from "./types.ts";
 
 export const DEFAULT_MCP_OUTPUT_MAX_BYTES = 50 * 1024;
@@ -10,7 +10,9 @@ export const DEFAULT_MCP_DETAILS_MAX_BYTES = 16 * 1024;
 
 const CONTENT_SUMMARY_LIMIT = 20;
 const KEY_PREVIEW_LIMIT = 20;
-const KEY_MAX_CHARS = 120;
+const KEY_MAX_BYTES = 120;
+const STRUCTURED_CONTENT_PRESERVE_MAX_BYTES = 4 * 1024;
+const STRUCTURED_CONTENT_FIELD_PRESERVE_MAX_BYTES = 512;
 
 type Recordish = Record<string, unknown>;
 
@@ -269,7 +271,33 @@ async function boundMcpResult(result: unknown, detailsMaxBytes: number): Promise
   const raw = safeStringify(result);
   const rawBytes = byteLength(raw);
   if (rawBytes <= detailsMaxBytes) return result;
-  return summarizeMcpResult(result, raw, rawBytes);
+  const marker = { omitted: true } as const;
+  if (byteLength(safeStringify(marker)) > detailsMaxBytes) return undefined;
+
+  const summary = await summarizeMcpResult(result, raw, rawBytes);
+  if (byteLength(safeStringify(summary)) <= detailsMaxBytes) return summary;
+  return compactMcpResultOmission(summary, marker, detailsMaxBytes);
+}
+
+async function compactMcpResultOmission(
+  summary: McpResultSummary,
+  marker: Readonly<{ omitted: true }>,
+  maxBytes: number,
+): Promise<unknown> {
+  if (summary.fullResultPath) {
+    const withPathAndSize = {
+      ...marker,
+      rawResultBytes: summary.rawResultBytes,
+      fullResultPath: summary.fullResultPath,
+    };
+    if (byteLength(safeStringify(withPathAndSize)) <= maxBytes) return withPathAndSize;
+    const withPath = { ...marker, fullResultPath: summary.fullResultPath };
+    if (byteLength(safeStringify(withPath)) <= maxBytes) return withPath;
+    await discardArtifact(summary.fullResultPath);
+  }
+
+  const withSize = { ...marker, rawResultBytes: summary.rawResultBytes };
+  return byteLength(safeStringify(withSize)) <= maxBytes ? withSize : marker;
 }
 
 async function summarizeMcpResult(result: unknown, raw: string, rawBytes: number): Promise<McpResultSummary> {
@@ -289,7 +317,7 @@ async function summarizeMcpResult(result: unknown, raw: string, rawBytes: number
   };
 
   if (record && "structuredContent" in record) {
-    summary.structuredContent = summarizeValue(record.structuredContent);
+    summary.structuredContent = summarizeStructuredContent(record.structuredContent);
   }
   if (record && "_meta" in record) {
     summary.meta = summarizeValue(record._meta);
@@ -336,11 +364,41 @@ function summarizeValue(value: unknown): Record<string, unknown> {
     type: Array.isArray(value) ? "array" : "object",
     estimatedBytes: estimateValueBytes(value),
     keyCount: keys.length,
-    keysPreview: keys.slice(0, KEY_PREVIEW_LIMIT).map(truncateKey),
+    keysPreview: uniqueBoundedKeys(keys.slice(0, KEY_PREVIEW_LIMIT)),
     omitted: true,
   };
 }
 
+function summarizeStructuredContent(value: unknown): Record<string, unknown> {
+  const record = asRecord(value);
+  if (!record || Array.isArray(value)) return summarizeValue(value);
+  const keys = Object.keys(record);
+  const entries = Object.entries(record).slice(0, KEY_PREVIEW_LIMIT);
+  const previewKeys = uniqueBoundedKeys(entries.map(([key]) => key));
+  const fields: Record<string, unknown> = {};
+  let preservedBytes = byteLength("{}");
+  for (const [key, field] of entries) {
+    const fieldBytes = byteLength(safeStringify(field));
+    const candidate = fieldBytes <= STRUCTURED_CONTENT_FIELD_PRESERVE_MAX_BYTES
+      ? field
+      : summarizeValue(field);
+    const entryBytes = serializedObjectEntryBytes(key, candidate, Object.keys(fields).length > 0);
+    if (preservedBytes + entryBytes > STRUCTURED_CONTENT_PRESERVE_MAX_BYTES) continue;
+    fields[key] = candidate;
+    preservedBytes += entryBytes;
+  }
+  return {
+    preservedFields: fields,
+    summary: {
+      type: "object",
+      estimatedBytes: estimateValueBytes(value),
+      keyCount: keys.length,
+      keysPreview: previewKeys,
+      omitted: true,
+    },
+  };
+}
+
 function estimateValueBytes(value: unknown, depth = 0): number {
   if (value === null || value === undefined) return 0;
   if (typeof value === "string") return byteLength(value);
@@ -352,7 +410,29 @@ function estimateValueBytes(value: unknown, depth = 0): number {
 }
 
 function truncateKey(key: string): string {
-  return key.length <= KEY_MAX_CHARS ? key : `${key.slice(0, KEY_MAX_CHARS - 1)}…`;
+  if (byteLength(key) <= KEY_MAX_BYTES) return key;
+  const suffix = "…";
+  return `${truncateStringToBytes(key, KEY_MAX_BYTES - byteLength(suffix))}${suffix}`;
+}
+
+function uniqueBoundedKeys(keys: string[]): string[] {
+  const used = new Set<string>();
+  return keys.map((key) => {
+    let candidate = truncateKey(key);
+    let ordinal = 2;
+    while (used.has(candidate)) {
+      const suffix = `~${ordinal}`;
+      candidate = `${truncateStringToBytes(key, KEY_MAX_BYTES - byteLength(suffix))}${suffix}`;
+      ordinal += 1;
+    }
+    used.add(candidate);
+    return candidate;
+  });
+}
+
+function serializedObjectEntryBytes(key: string, value: unknown, hasPrevious: boolean): number {
+  const serialized = safeStringify({ [key]: value });
+  return Math.max(0, byteLength(serialized) - byteLength("{}")) + (hasPrevious ? 1 : 0);
 }
 
 async function saveArtifact(kind: string, text: string): Promise<{ path?: string; error?: string }> {
@@ -366,6 +446,14 @@ async function saveArtifact(kind: string, text: string): Promise<{ path?: string
   }
 }
 
+async function discardArtifact(path: string): Promise<void> {
+  try {
+    await rm(dirname(path), { recursive: true, force: true });
+  } catch {
+    // Cleanup cannot increase the returned details payload.
+  }
+}
+
 function asRecord(value: unknown): Recordish | undefined {
   return typeof value === "object" && value !== null ? value as Recordish : undefined;
 }

package/dist/humain/mcp-adapter/vendor/mcp-probe.ts

@@ -5,6 +5,7 @@ const JSON_ACCEPT = "application/json, text/event-stream";
 const SSE_ACCEPT = "text/event-stream";
 const MODERN_FALLBACK_STATUSES = new Set([400, 401, 404, 405, 406, 415]);
 const POST_ENDPOINT_MISMATCH_STATUSES = new Set([404, 405, 406, 415]);
+const AMBIGUOUS_STATUSES = new Set([202, 401, 503]);
 
 export interface McpProbeResult {
   isMcp: boolean;
@@ -163,25 +164,38 @@ async function probe(url: string | URL, strategy: ProbeStrategy): Promise<ProbeR
 }
 
 function notMcp(response: Response): McpProbeResult {
+  const responseDescription = `endpoint returned ${responseKind(response)} (${response.status})`;
   return {
     isMcp: false,
-    classification: `endpoint returned ${responseKind(response)} (${response.status}) — this URL does not appear to speak MCP`,
+    classification: response.status === 503
+      ? `${responseDescription} — server is temporarily unavailable; MCP endpoint shape could not be determined`
+      : response.status === 202
+        ? `${responseDescription} — MCP endpoint shape could not be determined`
+      : response.status === 401
+        ? `${responseDescription} — authentication may be required; MCP endpoint shape could not be determined`
+        : `${responseDescription} — this URL does not appear to speak MCP`,
   };
 }
 
+function ambiguousNotMcp(response: Response): McpProbeResult | undefined {
+  return AMBIGUOUS_STATUSES.has(response.status) ? notMcp(response) : undefined;
+}
+
 /** Makes one unauthenticated metadata-only request to identify an HTTP endpoint's protocol shape. */
 export async function probeMcpEndpoint(url: string | URL): Promise<McpProbeResult> {
   const { response: modernResponse, outcome: modernOutcome } = await probe(url, MODERN_STRATEGY);
   if (modernOutcome.kind === "mcp") return modernOutcome.result;
+  let ambiguousResult = ambiguousNotMcp(modernResponse);
 
   if (modernOutcome.kind !== "unsupported-modern" && !MODERN_FALLBACK_STATUSES.has(modernResponse.status)) {
-    return notMcp(modernResponse);
+    return ambiguousResult ?? notMcp(modernResponse);
   }
 
   const { response: postResponse, outcome: postOutcome } = await probe(url, LEGACY_POST_STRATEGY);
   if (postOutcome.kind === "mcp") return postOutcome.result;
-  if (!POST_ENDPOINT_MISMATCH_STATUSES.has(postResponse.status)) return notMcp(postResponse);
+  ambiguousResult ??= ambiguousNotMcp(postResponse);
+  if (!POST_ENDPOINT_MISMATCH_STATUSES.has(postResponse.status)) return ambiguousNotMcp(postResponse) ?? ambiguousResult ?? notMcp(postResponse);
 
   const { response: getResponse, outcome: getOutcome } = await probe(url, LEGACY_SSE_STRATEGY);
-  return getOutcome.kind === "mcp" ? getOutcome.result : notMcp(getResponse);
+  return getOutcome.kind === "mcp" ? getOutcome.result : ambiguousNotMcp(getResponse) ?? ambiguousResult ?? notMcp(getResponse);
 }