@aion0/forge 0.10.28 → 0.10.29

package/RELEASE_NOTES.md

@@ -1,11 +1,20 @@
-# Forge v0.10.28
+# Forge v0.10.29
 
 Released: 2026-06-02
 
-## Changes since v0.10.27
+## Changes since v0.10.28
 
 ### Other
-- fix(login-status): remove GitLab 2FA row — 2fa_verify is interactive, can't probe
+- feat(ssh): template-expand spec.timeout_sec — lets tools surface as arg
+- fix(help-content): drop import.meta.url branch — Turbopack rejects webpackIgnore
+- fix(help-content): suppress Turbopack 'cannot resolve ./help-docs' warning
+- fix(http): empty-string body resolves to no-body
+- fix(http-auth): bearer-token-exchange honours connector http.verify_tls
+- feat(connector-test): add body_match regex for response-body validation
+- fix(http): reorder method-template expand to AFTER argsWithDefaults
+- fix(http): expand templates in spec.method before uppercase
+- docs(connector-authoring): add bearer-token-exchange section to 21-build-connector
+- feat(http-auth): bearer-token-exchange supports body-mode + bare format
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.27...v0.10.28
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.28...v0.10.29

package/lib/chat/protocols/http.ts

@@ -191,6 +191,7 @@ async function exchangeBearerToken(
   auth: Extract<ConnectorAuth, { type: 'bearer-token-exchange' }>,
   settings: Record<string, any>,
   args: Record<string, any>,
+  verifyTls?: boolean,
 ): Promise<string> {
   const exp = (s: string | undefined) =>
     s == null ? '' : expandAllTokens(String(s), settings, args);
@@ -198,24 +199,57 @@ async function exchangeBearerToken(
   // Same pathname-only collapse as buildUrl — guards against trailing
   // slash on settings.base_url producing `host//api/...`.
   const exchangeUrl = collapsePathSlashes(exp(auth.exchange_url));
-  if (!apiToken) throw new Error('bearer-token-exchange: api_token is empty');
   if (!exchangeUrl) throw new Error('bearer-token-exchange: exchange_url is empty');
-  const key = `${apiToken}|${exchangeUrl}`;
+
+  // Two credential modes:
+  //   header-mode → exchange_auth_header (BD: "token <api_token>")
+  //   body-mode   → exchange_body (NCM: {username, password})
+  // Cache key derives from whichever credential identity is in play, so
+  // password rotation invalidates cache, and multi-host installs cache
+  // per (host, credentials) pair.
+  const usingBody = !!auth.exchange_body;
+  const credIdentity = usingBody
+    ? JSON.stringify(
+        Object.fromEntries(
+          Object.entries(auth.exchange_body!).map(([k, v]) => [k, exp(String(v ?? ''))]),
+        ),
+      )
+    : apiToken;
+  if (!credIdentity) throw new Error('bearer-token-exchange: no credentials (api_token or exchange_body)');
+  const key = `${credIdentity}|${exchangeUrl}`;
   const cached = _bearerCache.get(key);
   if (cached && cached.expiresAt > Date.now() + 60_000) return cached.bearer;
 
-  const authHeader = exp(auth.exchange_auth_header || `token ${auth.api_token}`);
-  const headers: Record<string, string> = { Authorization: authHeader };
+  const headers: Record<string, string> = {};
+  let body: string | undefined;
+  if (usingBody) {
+    headers['content-type'] = 'application/json';
+    const expanded: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(auth.exchange_body!)) {
+      expanded[k] = typeof v === 'string' ? exp(v) : v;
+    }
+    body = JSON.stringify(expanded);
+  } else {
+    headers['Authorization'] = exp(auth.exchange_auth_header || `token ${auth.api_token}`);
+  }
   if (auth.exchange_headers) {
     for (const [k, v] of Object.entries(auth.exchange_headers)) headers[k] = exp(v);
   }
-  const res = await fetch(exchangeUrl, {
-    method: auth.exchange_method || 'POST',
-    headers,
-  });
+  // Honour connector-level http.verify_tls — self-signed appliances
+  // (NCM, NAC, ESXi …) need undici with rejectUnauthorized:false. Default
+  // fetch barfs with "fetch failed" otherwise.
+  const exchangeFetchInit = { method: auth.exchange_method || 'POST', headers, body };
+  let res: Response;
+  if (verifyTls === false) {
+    const { fetch: undiciFetch, Agent } = await import('undici');
+    const dispatcher = new Agent({ connect: { rejectUnauthorized: false } });
+    res = await undiciFetch(exchangeUrl, { ...exchangeFetchInit, dispatcher }) as unknown as Response;
+  } else {
+    res = await fetch(exchangeUrl, exchangeFetchInit);
+  }
   if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throw new Error(`bearer-token-exchange: ${res.status} ${res.statusText}: ${body.slice(0, 200)}`);
+    const errBody = await res.text().catch(() => '');
+    throw new Error(`bearer-token-exchange: ${res.status} ${res.statusText}: ${errBody.slice(0, 200)}`);
   }
   const j: any = await res.json().catch(() => ({}));
   const bearer = pickByPath(j, auth.bearer_path, 'bearerToken');
@@ -223,8 +257,9 @@ async function exchangeBearerToken(
   if (typeof bearer !== 'string' || !bearer) {
     throw new Error(`bearer-token-exchange: missing bearer at "${auth.bearer_path || 'bearerToken'}" in response`);
   }
-  // Cache for the reported TTL, or 5 minutes if not provided.
-  const ttl = expiresMs > 0 ? expiresMs : 5 * 60 * 1000;
+  // Cache for the reported TTL, the fallback ttl, or 5 min default.
+  const fallbackMs = (auth.expires_ttl_sec || 300) * 1000;
+  const ttl = expiresMs > 0 ? expiresMs : fallbackMs;
   _bearerCache.set(key, { bearer, expiresAt: Date.now() + ttl });
   return bearer;
 }
@@ -235,6 +270,7 @@ export async function applyAuth(
   auth: ConnectorAuth | undefined,
   settings: Record<string, any>,
   args: Record<string, any> = {},
+  verifyTls?: boolean,
 ): Promise<string> {
   if (!auth || auth.type === 'none') return url;
   const exp = (s: string) => expandAllTokens(String(s ?? ''), settings, args);
@@ -260,8 +296,9 @@ export async function applyAuth(
       return u.toString();
     }
     case 'bearer-token-exchange': {
-      const bearer = await exchangeBearerToken(auth, settings, args);
-      headers.set('Authorization', `Bearer ${bearer}`);
+      const bearer = await exchangeBearerToken(auth, settings, args, verifyTls);
+      const format = auth.bearer_format || 'bearer';
+      headers.set('Authorization', format === 'bare' ? bearer : `Bearer ${bearer}`);
       return url;
     }
   }
@@ -281,7 +318,13 @@ function buildHeaders(spec: HttpRequestSpec, settings: Record<string, any>, args
 function buildBody(spec: HttpRequestSpec, settings: Record<string, any>, args: Record<string, any>): { body?: string; contentType?: string } {
   if (spec.body != null) {
     if (typeof spec.body === 'string') {
-      return { body: expandAllTokens(spec.body, settings, args) };
+      const expanded = expandAllTokens(spec.body, settings, args);
+      // Empty string after expansion = no body. Lets manifests use
+      // `body: "{args.body_json}"` with an empty default — Forge sends
+      // no body for GET/DELETE-style calls without the LLM needing to
+      // know about the body field at all.
+      if (expanded === '') return {};
+      return { body: expanded };
     }
     const obj = expandObjectLeaves(spec.body, settings, args);
     return { body: JSON.stringify(obj), contentType: 'application/json' };
@@ -389,7 +432,6 @@ export async function runHttp({ tool, settings, args, connectorAuth, noTruncatio
   if (!spec || !spec.url) {
     return { content: 'http tool missing `request.url`', is_error: true };
   }
-  const method = (spec.method || 'GET').toUpperCase();
   const timeoutMs = Math.min(MAX_TIMEOUT_MS, Math.max(1, Number(tool.timeout_ms || DEFAULT_TIMEOUT_MS)));
 
   // Apply parameter defaults from the manifest so templates like
@@ -405,6 +447,13 @@ export async function runHttp({ tool, settings, args, connectorAuth, noTruncatio
     }
   }
 
+  // Expand `{args.method}` etc. before uppercasing — call_api-style tools
+  // template the method from a tool param. Without expansion the literal
+  // `{args.method}` reached fetch as `{ARGS.METHOD}` and bombed with
+  // "is not a valid HTTP method".
+  const rawMethod = expandAllTokens(spec.method || 'GET', settings, argsWithDefaults);
+  const method = (rawMethod || 'GET').toUpperCase();
+
   let url = buildUrl(spec, settings, argsWithDefaults, tool.parameters);
   const headers = buildHeaders(spec, settings, argsWithDefaults);
   const { body, contentType } = buildBody(spec, settings, argsWithDefaults);
@@ -413,7 +462,7 @@ export async function runHttp({ tool, settings, args, connectorAuth, noTruncatio
   // Tool-level auth overrides connector-level. `{ type: 'none' }` is a
   // valid override that disables auth entirely (public endpoint).
   const effectiveAuth = tool.auth ?? connectorAuth;
-  url = await applyAuth(url, headers, effectiveAuth, settings, argsWithDefaults);
+  url = await applyAuth(url, headers, effectiveAuth, settings, argsWithDefaults, verifyTls);
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);

package/lib/chat/protocols/ssh.ts

@@ -104,7 +104,10 @@ export async function runSsh({ tool, settings, args }: SshProtocolArgs): Promise
   const doneRe = rx(spec.done_when);
   const failRe = rx(spec.fail_when);
   const passwordRe = /password:\s*$/i;
-  const timeoutMs = Math.min(MAX_TIMEOUT_MS, Math.max(2_000, Number(spec.timeout_sec || 0) * 1000 || DEFAULT_TIMEOUT_MS));
+  // timeout_sec is templated so tools can expose it as an arg
+  // (e.g. nac.run_command for long-running `diagnose host list all`).
+  const rawTimeout = spec.timeout_sec != null ? exp(String(spec.timeout_sec)) : '';
+  const timeoutMs = Math.min(MAX_TIMEOUT_MS, Math.max(2_000, Number(rawTimeout || 0) * 1000 || DEFAULT_TIMEOUT_MS));
 
   const sshArgs = [
     '-tt',                                       // force PTY for interactive prompts

package/lib/connectors/test-runner.ts

@@ -117,7 +117,7 @@ async function runHttpProbe(
     headers.set('content-type', contentType);
   }
   try {
-    url = await applyAuth(url, headers, def.auth, effectiveSettings);
+    url = await applyAuth(url, headers, def.auth, effectiveSettings, {}, def.http?.verify_tls);
   } catch (e) {
     return { ok: false, error: `auth setup failed: ${(e as Error).message}` };
   }
@@ -164,6 +164,34 @@ async function runHttpProbe(
     };
   }
 
+  // body_match — gate the test on response body content (e.g. version
+  // check). Applies BEFORE ok_template rendering.
+  if (test.body_match) {
+    let pattern: RegExp;
+    try {
+      pattern = new RegExp(test.body_match);
+    } catch (e) {
+      return {
+        ok: false,
+        status: res.status,
+        error: `invalid body_match regex "${test.body_match}": ${(e as Error).message}`,
+        duration_ms: duration,
+        body_preview: preview,
+      };
+    }
+    if (!pattern.test(text)) {
+      const errMsg = test.body_match_error
+        || `body did not match expected pattern /${test.body_match}/ — got: ${preview.slice(0, 100)}`;
+      return {
+        ok: false,
+        status: res.status,
+        error: errMsg,
+        duration_ms: duration,
+        body_preview: preview,
+      };
+    }
+  }
+
   let parsedBody: unknown = null;
   try { parsedBody = JSON.parse(text); } catch {}
   const message = test.ok_template

package/lib/connectors/types.ts

@@ -171,23 +171,52 @@ export type ConnectorAuth =
    */
   | {
       type: 'bearer-token-exchange';
-      /** Long-lived API token sent to the exchange endpoint. Templated. */
-      api_token: string;
-      /** Exchange URL. Templated — usually `{base_url}/api/tokens/authenticate`. */
+      /**
+       * Long-lived API token sent to the exchange endpoint (BD-style
+       * auth via Authorization header). Optional — omit when using
+       * username/password via `exchange_body` (NCM-style).
+       */
+      api_token?: string;
+      /**
+       * Exchange URL. Templated against settings + args, so `{args.host}`
+       * works for connectors that take host per call. Cache key includes
+       * the resolved URL so multi-host installs cache per host.
+       */
       exchange_url: string;
       /** HTTP method for the exchange. Default POST. */
       exchange_method?: 'POST' | 'GET';
       /**
        * Authorization header VALUE sent to the exchange endpoint.
-       * Default `token {api_token}` (Black Duck style). Templated.
+       * Default `token {api_token}` (Black Duck style). Ignored when
+       * `exchange_body` is set. Templated.
        */
       exchange_auth_header?: string;
       /** Extra headers (Accept etc.) for the exchange. Values templated. */
       exchange_headers?: Record<string, string>;
+      /**
+       * JSON body for the exchange POST (NCM-style username/password
+       * login). String values templated against settings + args. When
+       * present, content-type is application/json and
+       * `exchange_auth_header` is skipped.
+       */
+      exchange_body?: Record<string, unknown>;
       /** JSON path to the bearer in the exchange response. Default `bearerToken`. */
       bearer_path?: string;
       /** JSON path to expiry ms in the exchange response. Default `expiresInMilliseconds`. */
       expires_path?: string;
+      /**
+       * Fallback TTL in seconds when `expires_path` is missing from the
+       * response. Useful for APIs whose JWT carries `exp` inside the
+       * payload but isn't echoed at the response top level. Default 300.
+       */
+      expires_ttl_sec?: number;
+      /**
+       * How to attach the bearer to subsequent requests:
+       *   `bearer` (default) → `Authorization: Bearer <token>`
+       *   `bare`             → `Authorization: <token>` (NCM, NAC,
+       *                         some legacy APIs)
+       */
+      bearer_format?: 'bearer' | 'bare';
     };
 
 /**
@@ -410,6 +439,21 @@ export interface ConnectorTest {
    * Example: "Authenticated as {{username}} ({{name}})".
    */
   ok_template?: string;
+  /**
+   * Optional regex (JS syntax) that the response body must match for
+   * the test to pass. Use for version gates or feature flags — e.g.
+   * `^(8|9|[1-9]\\d)\\.` to require version 8.x or newer. On mismatch
+   * the test fails with a descriptive error including the actual body
+   * snippet, so users see immediately why the connector won't work
+   * against their server build.
+   */
+  body_match?: string;
+  /**
+   * Custom error message shown when `body_match` fails. Defaults to
+   * "body did not match expected pattern <regex>". Use when you want
+   * to point users at a specific upgrade / config requirement.
+   */
+  body_match_error?: string;
 
   // ── probe: 'browser' ─────────────────────────────────────
   // No fields required — the extension reuses the connector's

package/lib/help-content.ts

@@ -1,28 +1,22 @@
 /**
  * Help-doc reader for the chat agent's read_help_doc / list_help_docs tools.
  *
- * Reads the markdown docs that ship under lib/help-docs/ (same set the Help AI
- * terminal uses). Resolved relative to this module so it works regardless of
- * whether the on-disk sync (ensureHelpDocs → <config>/help) has run yet, then
- * falls back to the synced copy if the source tree isn't present (installed
- * tarball layouts).
+ * Reads the markdown docs synced to <configDir>/help by lib/init.ts on first
+ * API request (which runs before any chat call). The source tree at
+ * lib/help-docs/ is the authoring location; init.ts copies it out at startup.
  */
 
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { getConfigDir } from './dirs';
 
-// Candidate dirs, in priority order: source tree next to this module, then the
-// synced runtime copy under ~/.forge/help.
+// Authoritative runtime location — populated by ensureHelpDocs() on init.
+// We used to also probe `new URL('./help-docs', import.meta.url)` as a
+// dev-mode shortcut, but bundlers (Turbopack/webpack) can't ignore the
+// static analysis cleanly and the synced copy is always present in
+// practice, so it's gone.
 function helpDirs(): string[] {
-  const dirs: string[] = [];
-  try {
-    const here = fileURLToPath(new URL('./help-docs', import.meta.url));
-    dirs.push(here);
-  } catch { /* import.meta.url unavailable (CJS bundle) — skip */ }
-  dirs.push(join(getConfigDir(), 'help'));
-  return dirs;
+  return [join(getConfigDir(), 'help')];
 }
 
 /** List available help-doc filenames (e.g. ["00-overview.md", ...]), sorted. */

package/lib/help-docs/21-build-connector.md

@@ -176,6 +176,66 @@ auth:
 
 A tool can override (or disable) the inherited scheme with its own `auth:` block. `{ type: none }` skips auth entirely (public endpoint).
 
+##### `bearer-token-exchange` — auto-refreshing JWTs
+
+For APIs that don't accept static tokens — you POST credentials to an exchange endpoint, get a short-lived JWT/bearer, then use that on every subsequent call. Two real-world flavours, both handled by the same auth type:
+
+**Flavour A — header-mode (Black Duck style)**. You have a long-lived API token; you send it in the Authorization header to the exchange URL.
+
+```yaml
+auth:
+  type: bearer-token-exchange
+  api_token: '{settings.api_token}'
+  exchange_url: '{settings.base_url}/api/tokens/authenticate'
+  exchange_method: POST                         # default
+  exchange_auth_header: 'token {settings.api_token}'   # default
+  exchange_headers:                             # optional vendored Accept
+    Accept: 'application/vnd.blackducksoftware.user-4+json'
+  bearer_path: bearerToken                      # default — JSON path in response
+  expires_path: expiresInMilliseconds           # default — JSON path in response
+  # bearer_format: bearer                       # default — sends 'Authorization: Bearer <jwt>'
+```
+
+**Flavour B — body-mode (FortiNCM / NAC / most appliances)**. You have username + password; you POST them as a JSON body to a login endpoint and the JWT comes back in some nested field. The server expects the bare token (no `Bearer ` prefix).
+
+```yaml
+auth:
+  type: bearer-token-exchange
+  exchange_url: 'https://{args.host}/api/v3/auth/login'   # {args.*} works — host can be per-call
+  exchange_method: POST
+  exchange_body:                                # JSON body; values templated
+    username: '{settings.username}'
+    password: '{settings.password}'
+  bearer_path: result.jwt                       # dotted path into response JSON
+  bearer_format: bare                           # → 'Authorization: <jwt>', no Bearer prefix
+  expires_ttl_sec: 540                          # fallback TTL when response doesn't include expiry
+```
+
+Forge handles the round-trip transparently: first tool call pays the exchange round-trip, the bearer is cached in-memory keyed by `<credential identity>|<resolved exchange_url>`, and refreshed when within 60s of expiry. Tools see only their own `args.*` — they never touch the token.
+
+Cache key derivation:
+- **Credential identity**: `api_token` (header-mode) OR the serialised expanded body (body-mode). Password rotation invalidates the cache.
+- **Resolved exchange_url**: settings + args fully resolved, so multi-host installs (`{args.host}` in URL) cache per-host independently.
+
+All fields are templated:
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `exchange_url` | yes | — | `{settings.*}` and `{args.*}` both work |
+| `exchange_method` | no | `POST` | `POST` or `GET` |
+| `api_token` | no¹ | — | Header-mode credential |
+| `exchange_auth_header` | no | `token {api_token}` | Ignored when `exchange_body` is set |
+| `exchange_body` | no¹ | — | JSON body for body-mode login |
+| `exchange_headers` | no | — | Extra request headers for the exchange |
+| `bearer_path` | no | `bearerToken` | Dotted path into response JSON |
+| `expires_path` | no | `expiresInMilliseconds` | If missing in response → use `expires_ttl_sec` |
+| `expires_ttl_sec` | no | `300` | Fallback TTL (seconds) |
+| `bearer_format` | no | `bearer` | `bearer` → `Authorization: Bearer <jwt>`; `bare` → `Authorization: <jwt>` |
+
+¹ Provide ONE of `api_token` or `exchange_body`.
+
+When picking between the two: if the API has its own "Generate API token" UI for users, prefer header-mode (token rotates rarely, user manages it). If the API only accepts username/password login, use body-mode (Forge stores the password encrypted in settings).
+
 #### Per-parameter URL encoding
 
 Default behaviour for an `{args.X}` in a URL path is `encodeURIComponent` — slashes become `%2F`. This is right for GitLab-style project paths but wrong for systems that expect literal slashes (Jenkins folder paths). Override per parameter:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.10.28",
+  "version": "0.10.29",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {