@adcp/sdk 7.0.0 → 7.2.0

package/bin/adcp.js

@@ -266,6 +266,163 @@ function mergeHeaders(savedHeaders, cliHeaders) {
   return Object.keys(filtered).length > 0 ? filtered : undefined;
 }
 
+/**
+ * Parse `--auth-scheme bearer|basic`. Defaults to `bearer` (preserving the
+ * pre-existing CLI contract where `--auth TOKEN` is always a bearer). When
+ * the flag is absent, falls back to the `ADCP_AUTH_SCHEME` env var so CI
+ * jobs can flip the scheme without rewriting their command line. Returns
+ * `null` when neither the flag nor the env var supplied a value — callers
+ * use that to defer to a saved alias's `auth_scheme`.
+ */
+function parseAuthSchemeFlag(args) {
+  let value = null;
+  let source = null;
+  // Long-form: --auth-scheme VALUE
+  const longIdx = args.indexOf('--auth-scheme');
+  if (longIdx !== -1) {
+    if (longIdx + 1 >= args.length || args[longIdx + 1].startsWith('--')) {
+      console.error('ERROR: --auth-scheme requires a value (bearer|basic)\n');
+      process.exit(2);
+    }
+    value = args[longIdx + 1];
+    source = 'flag';
+  }
+  // Single-token form: --auth-scheme=VALUE. Security-reviewer L3 from PR #1719
+  // flagged that the long-form path treats `--auth-scheme=basic` (no space) as
+  // an unknown arg, which silently falls through to env-var lookup. Match the
+  // other flags' equals-form by checking for the literal prefix explicitly.
+  if (value === null) {
+    const eqArg = args.find(a => a.startsWith('--auth-scheme='));
+    if (eqArg) {
+      value = eqArg.slice('--auth-scheme='.length);
+      source = 'flag';
+    }
+  }
+  if (value === null && process.env.ADCP_AUTH_SCHEME) {
+    value = process.env.ADCP_AUTH_SCHEME;
+    source = 'env';
+  }
+  if (value === null) return null;
+  if (value !== 'bearer' && value !== 'basic') {
+    // Name the source in the error so the operator knows whether to fix the
+    // flag invocation or the environment variable.
+    const sourceLabel = source === 'env' ? 'ADCP_AUTH_SCHEME env var' : '--auth-scheme';
+    console.error(`ERROR: ${sourceLabel} must be 'bearer' or 'basic', got: ${value}\n`);
+    process.exit(2);
+  }
+  return value;
+}
+
+/**
+ * Warn when `ADCP_AUTH_SCHEME` was set in the environment but the resolved
+ * scheme didn't end up applied (because no token / no credential resolved to
+ * the request). The inverse case (token without scheme → silent bearer) is
+ * the safe direction and gets no warning.
+ *
+ * Called once per top-level invocation, after auth resolution completes.
+ * The check is purely advisory; it doesn't change behavior, just surfaces a
+ * likely misconfiguration before the user wonders why their Basic gateway
+ * keeps 401ing.
+ */
+function maybeWarnAuthSchemeIneffective(resolvedAuthToken, resolvedAuthScheme) {
+  const envScheme = process.env.ADCP_AUTH_SCHEME;
+  if (!envScheme) return;
+  if (envScheme !== 'bearer' && envScheme !== 'basic') return; // parse error already exited
+  // Effective: a token resolved AND the resolved scheme matches what the env
+  // asked for. If we have no token, basic is meaningless; if we have a token
+  // but the scheme resolved differently (e.g. saved alias overrode), the env
+  // is no-op-shadowed and worth flagging.
+  const effective = !!resolvedAuthToken && resolvedAuthScheme === envScheme;
+  if (!effective) {
+    console.error(
+      `Warning: ADCP_AUTH_SCHEME=${envScheme} is set but did not apply ` +
+        `(${!resolvedAuthToken ? 'no --auth / saved auth_token resolved' : `resolved scheme is '${resolvedAuthScheme}'`}). ` +
+        `Pass --auth (or an alias with credentials) to use the env-supplied scheme.`
+    );
+  }
+}
+
+/**
+ * Split a `user:pass` credential string and validate per RFC 7617:
+ *   - userid must not contain `:` (a colon would decode ambiguously on the
+ *     server, and undici/curl would mis-parse the cached header).
+ *   - CR, LF, and non-printable ASCII are rejected — these are the same
+ *     header-smuggling shapes parseHeaderFlags refuses on `-H` input.
+ *
+ * Returns `{ username, password }`. Exits 2 with a stderr message on any
+ * validation failure so the failure mode matches the rest of the CLI's
+ * argument validation (no half-encoded header reaches the wire).
+ */
+function decodeBasicCredentials(userpass, source = '--auth') {
+  if (typeof userpass !== 'string' || userpass.length === 0) {
+    console.error(`ERROR: ${source} value for basic auth must be 'user:pass' (got empty value)\n`);
+    process.exit(2);
+  }
+  const colon = userpass.indexOf(':');
+  if (colon === -1) {
+    // Don't echo the credential itself — even a length leak is enough to help
+    // someone reasoning about the value off-screen. The fix is the same
+    // regardless of what they passed in.
+    console.error(`ERROR: ${source} basic-auth credential must be in 'user:pass' form (no ':' found)\n`);
+    process.exit(2);
+  }
+  const username = userpass.slice(0, colon);
+  const password = userpass.slice(colon + 1);
+  if (username.length === 0) {
+    console.error(`ERROR: ${source} basic auth username must not be empty\n`);
+    process.exit(2);
+  }
+  if (username.includes(':')) {
+    // Impossible from a single-colon split, but kept as a defensive guard
+    // in case a future refactor changes the split logic.
+    console.error(`ERROR: ${source} basic auth username must not contain ':' (RFC 7617)\n`);
+    process.exit(2);
+  }
+  const badChar = /[\r\n\0]|[^\x20-\x7E]/;
+  if (badChar.test(username)) {
+    console.error(`ERROR: ${source} basic auth username contains CR, LF, NUL, or non-printable ASCII\n`);
+    process.exit(2);
+  }
+  if (badChar.test(password)) {
+    console.error(`ERROR: ${source} basic auth password contains CR, LF, NUL, or non-printable ASCII\n`);
+    process.exit(2);
+  }
+  return { username, password };
+}
+
+/**
+ * Encode RFC 7617 `Authorization: Basic <base64(user:pass)>` from a validated
+ * `{username, password}` pair. Caller MUST have run `decodeBasicCredentials`
+ * first — this helper does not re-validate.
+ */
+function encodeBasicAuthHeader({ username, password }) {
+  return `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+}
+
+/**
+ * Inject `Authorization: Basic <base64(user:pass)>` into the header map the
+ * CLI hands to the SDK. Called AFTER `mergeHeaders()` runs so the
+ * reserved-key filter doesn't strip the injected Authorization. The protocol
+ * layer (`src/lib/protocols/mcp.ts` and `protocols/a2a.ts`) spreads
+ * `customHeaders` BEFORE SDK-supplied Authorization, so this injected value
+ * reaches the wire intact only when the caller has suppressed `auth_token`
+ * (the bearer-path overrides Authorization in that case).
+ *
+ * **Invariant for future contributors**: this MUST be called after
+ * `mergeHeaders()` and the bearer-path `auth_token` must be omitted when
+ * `useBasicAuth` is true. Moving the injection inside `mergeHeaders()` would
+ * silently drop the header (reserved-key filter is case-insensitive on
+ * `authorization`). The test at
+ * `test/lib/cli-auth-scheme.test.js:'wire test'` is the regression guard —
+ * if a refactor moves the injection wrong, that test stops sending Basic.
+ *
+ * Returns the merged header bag (always defined, even if empty in).
+ */
+function injectBasicAuthHeader(mergedHeaders, userpass, source = '--auth') {
+  const { username, password } = decodeBasicCredentials(userpass, source);
+  return { ...(mergedHeaders || {}), Authorization: encodeBasicAuthHeader({ username, password }) };
+}
+
 /**
  * Extract human-readable protocol message from conversation
  */
@@ -439,6 +596,10 @@ async function handleTestCommand(args) {
     }
     authToken = args[authIndex + 1];
   }
+  // `--auth-scheme bearer|basic` selects how `--auth` (or the saved alias's
+  // auth_token) is sent. Default null → defer to saved alias's `auth_scheme`,
+  // then fall back to `bearer`.
+  const authScheme = parseAuthSchemeFlag(args);
 
   // adcp-client#1612: accept `--transport` as an alias for `--protocol`.
   // The original symptom report used `--transport a2a` (per A2A SDK
@@ -476,7 +637,7 @@ async function handleTestCommand(args) {
 
   // Filter out flag arguments to find positional arguments
   const positionalArgs = args.filter(
-    arg => !arg.startsWith('--') && arg !== authToken && arg !== protocolFlag && arg !== brief
+    arg => !arg.startsWith('--') && arg !== authToken && arg !== authScheme && arg !== protocolFlag && arg !== brief
   );
 
   if (positionalArgs.length === 0) {
@@ -507,6 +668,7 @@ async function handleTestCommand(args) {
   let agentUrl;
   let protocol = protocolFlag;
   let finalAuthToken = authToken;
+  let finalAuthScheme = authScheme; // null = defer to alias's saved scheme
   let oauthTokens = null;
 
   // Resolve agent
@@ -520,6 +682,9 @@ async function handleTestCommand(args) {
     agentUrl = savedAgent.url;
     protocol = protocol || savedAgent.protocol;
     finalAuthToken = finalAuthToken || getEffectiveAuthToken(savedAgent);
+    if (finalAuthScheme === null && savedAgent.auth_scheme) {
+      finalAuthScheme = savedAgent.auth_scheme;
+    }
     if (savedAgent.oauth_client_credentials) {
       // Client credentials: tokens are refreshed inside `ProtocolClient.callTool`
       // via `ensureClientCredentialsTokens`. Surface cached tokens so the call
@@ -583,11 +748,12 @@ async function handleTestCommand(args) {
     }
   }
 
-  // Build test options
+  // Build test options. `buildResolvedAuthOption` handles the bearer/basic
+  // split based on the resolved scheme (default: bearer).
   const testOptions = {
     protocol,
     brief,
-    ...(finalAuthToken && { auth: { type: 'bearer', token: finalAuthToken } }),
+    ...buildResolvedAuthOption({ resolvedAuth: finalAuthToken, resolvedAuthScheme: finalAuthScheme || 'bearer' }),
   };
 
   if (!jsonOutput) {
@@ -713,6 +879,9 @@ function parseAgentOptions(args) {
   if (authIndex !== -1 && authIndex + 1 < args.length && !args[authIndex + 1].startsWith('--')) {
     authToken = args[authIndex + 1];
   }
+  // `--auth-scheme bearer|basic` selects the scheme used to send `--auth`.
+  // Default (null) defers to the saved alias's `auth_scheme`, then to `bearer`.
+  const authScheme = parseAuthSchemeFlag(args);
 
   // adcp-client#1612: accept `--transport` as an alias for `--protocol`.
   // See parseStorboardArgs for full rationale.
@@ -894,6 +1063,7 @@ function parseAgentOptions(args) {
   // so falsy-but-valid values (e.g. port "0") aren't dropped from the filter.
   const flagValues = [
     authToken,
+    authScheme,
     protocolFlag,
     brief,
     contextValue,
@@ -921,6 +1091,7 @@ function parseAgentOptions(args) {
 
   return {
     authToken,
+    authScheme,
     protocolFlag,
     brief,
     file,
@@ -1105,6 +1276,7 @@ async function ensureOAuthTokensForAlias(alias, url, { quiet = false, allowHttp
  */
 function buildResolvedAuthOption({
   resolvedAuth,
+  resolvedAuthScheme,
   resolvedOauthTokens,
   resolvedOauthClient,
   resolvedOauthClientCredentials,
@@ -1128,6 +1300,21 @@ function buildResolvedAuthOption({
     };
   }
   if (resolvedAuth) {
+    if (resolvedAuthScheme === 'basic') {
+      // `resolvedAuth` is the raw `user:pass` string (from `--auth` or the
+      // saved alias's `auth_token`). Decode it here so both the storyboard
+      // runner and `createTestClient` receive the `type: 'basic'` shape they
+      // already know how to send (`src/lib/testing/storyboard/runner.ts:4176`
+      // and `src/lib/testing/client.ts:155`). Most paths validated at
+      // register/parse time already, so this is a second-line defense; the
+      // source string names the alias-resolved origin so a malformed
+      // hand-edited config surfaces with the right hint instead of "--auth".
+      const { username, password } = decodeBasicCredentials(
+        resolvedAuth,
+        'resolved basic credential (saved alias or --auth)'
+      );
+      return { auth: { type: 'basic', username, password } };
+    }
     return { auth: { type: 'bearer', token: resolvedAuth } };
   }
   return {};
@@ -1149,10 +1336,11 @@ function buildResolvedAuthOption({
  * function deliberately does NOT exchange — it just surfaces the saved
  * credentials so the caller can hand them to the testing/protocol layer.
  */
-async function resolveAgent(agentArg, authToken, protocolFlag, jsonOutput) {
+async function resolveAgent(agentArg, authToken, protocolFlag, jsonOutput, authScheme = null) {
   let agentUrl;
   let protocol = protocolFlag;
   let finalAuthToken = authToken;
+  let finalAuthScheme = authScheme; // Explicit CLI flag wins; null = defer.
   let oauthTokens;
   let oauthClient;
   let oauthClientCredentials;
@@ -1164,6 +1352,8 @@ async function resolveAgent(agentArg, authToken, protocolFlag, jsonOutput) {
     agentUrl = builtIn.url;
     protocol = protocol || builtIn.protocol;
     finalAuthToken = finalAuthToken || builtIn.auth_token;
+    // Built-ins are bearer-only — no basic-auth gateway in front of them.
+    if (finalAuthScheme === null) finalAuthScheme = 'bearer';
   } else if (isAlias(agentArg)) {
     const savedAgent = getAgent(agentArg);
     agentUrl = savedAgent.url;
@@ -1177,6 +1367,9 @@ async function resolveAgent(agentArg, authToken, protocolFlag, jsonOutput) {
       oauthClient = savedAgent.oauth_client;
     }
     finalAuthToken = finalAuthToken || getEffectiveAuthToken(savedAgent);
+    if (finalAuthScheme === null && savedAgent.auth_scheme) {
+      finalAuthScheme = savedAgent.auth_scheme;
+    }
     if (savedAgent.headers && Object.keys(savedAgent.headers).length > 0) {
       savedHeaders = { ...savedAgent.headers };
     }
@@ -1205,6 +1398,11 @@ async function resolveAgent(agentArg, authToken, protocolFlag, jsonOutput) {
     agentUrl,
     protocol,
     authToken: finalAuthToken,
+    // Default to 'bearer' so callers can compare without null-checking. The
+    // distinction between an explicit `bearer` and an absent flag is only
+    // meaningful during alias resolution above — once we've returned, the
+    // scheme has been resolved.
+    authScheme: finalAuthScheme || 'bearer',
     oauthTokens,
     oauthClient,
     oauthClientCredentials,
@@ -1387,6 +1585,7 @@ QUICK START:
 AGENT MANAGEMENT:
   --save-auth <alias> [url]   Save agent with alias
                                 Static bearer:   --auth <token> | --no-auth
+                                HTTP Basic:      --auth <user:pass> --auth-scheme basic
                                 OAuth (browser): --oauth
                                 OAuth (M2M):     --client-id <id> | --client-id-env <VAR>
                                                  --client-secret <s> | --client-secret-env <VAR>
@@ -1399,7 +1598,11 @@ AGENT MANAGEMENT:
 OPTIONS:
   --protocol PROTO  Force protocol: mcp or a2a (default: auto-detect)
   --transport PROTO  Alias for --protocol (A2A SDK convention)
-  --auth TOKEN      Authentication token
+  --auth TOKEN      Authentication token (or 'user:pass' with --auth-scheme basic)
+  --auth-scheme bearer|basic
+                    Send --auth as Bearer (default) or RFC 7617 Basic for
+                    gateway-fronted agents. Env: ADCP_AUTH_SCHEME. Details:
+                    "adcp --save-auth --help".
   -H, --header K=V  Extra HTTP header on every request (repeatable). Auth wins on conflict.
                     Common use: -H x-adcp-tenant=<id> for tenant routing behind a reverse proxy.
   --oauth           OAuth authentication (MCP only, opens browser)
@@ -1519,7 +1722,11 @@ OPTIONS:
   --context JSON      Pass context from previous step (step only)
   --request JSON      Override sample_request for the step (step only)
   --json              JSON output (recommended for LLM consumption)
-  --auth TOKEN        Authentication token
+  --auth TOKEN        Authentication token (or 'user:pass' with --auth-scheme basic)
+  --auth-scheme bearer|basic
+                      How --auth is sent (default: bearer). Use 'basic' for
+                      gateways that require RFC 7617 Authorization: Basic
+                      instead of Authorization: Bearer.
   --oauth             Run the browser OAuth flow inline if the saved alias
                       has no valid tokens yet. Requires a saved alias
                       (use --save-auth first for raw URLs). MCP only.
@@ -2067,7 +2274,17 @@ function enforceStrictFlags(args, removedFound) {
 
 async function handleStoryboardRun(args) {
   const opts = parseAgentOptions(args);
-  const { authToken, protocolFlag, jsonOutput, dryRun, positionalArgs, file: filePath, localAgent, format } = opts;
+  const {
+    authToken,
+    authScheme,
+    protocolFlag,
+    jsonOutput,
+    dryRun,
+    positionalArgs,
+    file: filePath,
+    localAgent,
+    format,
+  } = opts;
 
   enforceStrictFlags(args, warnRemovedFlags(args));
 
@@ -2152,11 +2369,12 @@ async function handleStoryboardRun(args) {
     agentUrl,
     protocol,
     authToken: resolvedAuth,
+    authScheme: resolvedAuthScheme,
     oauthTokens: resolvedOauthTokens,
     oauthClient: resolvedOauthClient,
     oauthClientCredentials: resolvedOauthClientCredentials,
     savedHeaders,
-  } = await resolveAgent(agentArg, authToken, protocolFlag, jsonOutput);
+  } = await resolveAgent(agentArg, authToken, protocolFlag, jsonOutput, authScheme);
 
   const mergedRunHeaders = mergeHeaders(savedHeaders, opts.customHeaders);
 
@@ -2222,6 +2440,7 @@ async function handleStoryboardRun(args) {
     protocol,
     ...buildResolvedAuthOption({
       resolvedAuth,
+      resolvedAuthScheme,
       resolvedOauthTokens,
       resolvedOauthClient,
       resolvedOauthClientCredentials,
@@ -2310,6 +2529,7 @@ async function handleStoryboardRun(args) {
       `${overallIcon} ${result.passed_count} passed, ${result.failed_count} failed, ${result.skipped_count} skipped (${result.total_duration_ms}ms)${hintTail}`
     );
     printStrictSummary(result.strict_validation_summary);
+    printNotices(result.notices);
   }
 
   if (opts.softFail && !result.overall_passed) printSoftFailBlock([result.storyboard_id], jsonOutput);
@@ -3135,6 +3355,23 @@ async function handleLocalAgentStoryboardRun(modulePath, args, opts) {
     `\n${overallIcon} ${result.passed_count} passed, ${result.failed_count} failed, ${result.skipped_count} skipped across ${result.results.length} storyboard(s)${hintTail}`
   );
   printStrictSummary(aggregateStrictSummaries(result.results.map(r => r.strict_validation_summary)));
+  // Aggregate notices across all storyboards in the run, deduped by `code`
+  // (matches ComplianceResult.notices semantics). Storyboard_ids on each
+  // notice carry which storyboards triggered it, so the rollup stays clean.
+  const aggregatedNotices = new Map();
+  for (const sb of result.results || []) {
+    for (const n of sb.notices || []) {
+      const existing = aggregatedNotices.get(n.code);
+      if (existing) {
+        for (const sid of n.storyboard_ids || []) {
+          if (!existing.storyboard_ids.includes(sid)) existing.storyboard_ids.push(sid);
+        }
+      } else {
+        aggregatedNotices.set(n.code, { ...n, storyboard_ids: [...(n.storyboard_ids || [])] });
+      }
+    }
+  }
+  printNotices([...aggregatedNotices.values()]);
   if (opts.softFail && !result.overall_passed) {
     printSoftFailBlock(
       result.results.filter(r => !r.overall_passed).map(r => r.storyboard_id),
@@ -3159,6 +3396,36 @@ function printStrictSummary(summary) {
   console.log(`${icon} strict: ${passed}/${checked} passed${tail}`);
 }
 
+/**
+ * Render the `notices` advisory surface (adcp-client#1704) in the
+ * default text output. Notices are decoupled from overall_passed —
+ * they describe protocol-compliance trajectory (deprecations, upcoming
+ * requirements) rather than pass/fail. Severity drives the icon:
+ *
+ *   - `future_required` → ⏰ (action needed before a named version cut)
+ *   - `deprecation`     → 🪦 (migrate away from the named claim/field)
+ *   - `info`            → ℹ️ (purely informational)
+ *
+ * Without this, notices land only in `--json` output and adopters who
+ * tail the default text output never see the signal. Stays silent when
+ * `notices` is empty or absent.
+ */
+function printNotices(notices) {
+  if (!Array.isArray(notices) || notices.length === 0) return;
+  const icon = sev => {
+    if (sev === 'future_required') return '⏰';
+    if (sev === 'deprecation') return '🪦';
+    return 'ℹ️ ';
+  };
+  for (const n of notices) {
+    const tag = (n.severity || 'info').toUpperCase().replace('_', '-');
+    const version = n.effective_version ? ` (effective in ${n.effective_version})` : '';
+    console.log(`${icon(n.severity)} ${tag}: ${n.code}${version}`);
+    if (n.message) console.log(`   ${n.message}`);
+    if (n.docs_url) console.log(`   ↳ ${n.docs_url}`);
+  }
+}
+
 /**
  * Aggregate per-storyboard strict summaries into one. Runs are
  * independent grading passes against the same SDK; summing their
@@ -3188,7 +3455,7 @@ function aggregateStrictSummaries(summaries) {
 }
 
 async function handleMultiInstanceStoryboardRun(args, opts, urls) {
-  const { authToken, protocolFlag, jsonOutput, dryRun, positionalArgs, file: filePath } = opts;
+  const { authToken, authScheme, protocolFlag, jsonOutput, dryRun, positionalArgs, file: filePath } = opts;
 
   if (urls.length < 2) {
     console.error('ERROR: Multi-instance mode requires 2+ --url flags. Drop --url for single-instance.');
@@ -3397,7 +3664,7 @@ async function handleMultiInstanceStoryboardRun(args, opts, urls) {
 
   const runOptions = {
     protocol,
-    ...(authToken ? { auth: { type: 'bearer', token: authToken } } : {}),
+    ...buildResolvedAuthOption({ resolvedAuth: authToken, resolvedAuthScheme: authScheme || 'bearer' }),
     ...(opts.allowHttp && { allow_http: true }),
     multi_instance_strategy: strategy,
     ...(webhookReceiverOpts ?? {}),
@@ -3508,7 +3775,7 @@ async function handleMultiInstanceStoryboardRun(args, opts, urls) {
  * Storyboard ID, bundle ID, or `--file` is required.
  */
 async function handleAgentsRoutedStoryboardRun(args, opts, routing) {
-  const { authToken, protocolFlag, jsonOutput, dryRun, positionalArgs, file: filePath, format } = opts;
+  const { authToken, authScheme, protocolFlag, jsonOutput, dryRun, positionalArgs, file: filePath, format } = opts;
 
   const webhookAutoTunnel = args.includes('--webhook-receiver-auto-tunnel');
   const webhookReceiverBase = extractWebhookReceiverOptions(args);
@@ -3655,7 +3922,7 @@ async function handleAgentsRoutedStoryboardRun(args, opts, routing) {
 
   const runOptions = {
     protocol,
-    ...(authToken ? { auth: { type: 'bearer', token: authToken } } : {}),
+    ...buildResolvedAuthOption({ resolvedAuth: authToken, resolvedAuthScheme: authScheme || 'bearer' }),
     ...(opts.allowHttp && { allow_http: true }),
     agents: routing.agents,
     ...(routing.default_agent ? { default_agent: routing.default_agent } : {}),
@@ -3783,11 +4050,12 @@ async function runFullAssessment(agentArg, rawArgs, parsedOpts) {
     agentUrl,
     protocol,
     authToken: finalAuthToken,
+    authScheme: finalAuthScheme,
     oauthTokens,
     oauthClient,
     oauthClientCredentials,
     savedHeaders,
-  } = await resolveAgent(agentArg, opts.authToken, opts.protocolFlag, opts.jsonOutput);
+  } = await resolveAgent(agentArg, opts.authToken, opts.protocolFlag, opts.jsonOutput, opts.authScheme);
 
   const mergedAssessmentHeaders = mergeHeaders(savedHeaders, opts.customHeaders);
 
@@ -3840,6 +4108,7 @@ async function runFullAssessment(agentArg, rawArgs, parsedOpts) {
 
   const { auth: authOption } = buildResolvedAuthOption({
     resolvedAuth: finalAuthToken,
+    resolvedAuthScheme: finalAuthScheme,
     resolvedOauthTokens: oauthTokens,
     resolvedOauthClient: oauthClient,
     resolvedOauthClientCredentials: oauthClientCredentials,
@@ -3999,7 +4268,7 @@ async function runFullAssessment(agentArg, rawArgs, parsedOpts) {
 
 async function handleStoryboardStepCmd(args) {
   const { getComplianceStoryboardById, runStoryboardStep } = await import('../dist/lib/testing/storyboard/index.js');
-  const { authToken, protocolFlag, jsonOutput, debug, positionalArgs } = parseAgentOptions(args);
+  const { authToken, authScheme, protocolFlag, jsonOutput, debug, positionalArgs } = parseAgentOptions(args);
 
   enforceStrictFlags(args, warnRemovedFlags(args));
 
@@ -4024,10 +4293,11 @@ async function handleStoryboardStepCmd(args) {
     agentUrl,
     protocol,
     authToken: resolvedAuth,
+    authScheme: resolvedAuthScheme,
     oauthTokens: resolvedOauthTokens,
     oauthClient: resolvedOauthClient,
     oauthClientCredentials: resolvedOauthClientCredentials,
-  } = await resolveAgent(agentArg, authToken, protocolFlag, jsonOutput);
+  } = await resolveAgent(agentArg, authToken, protocolFlag, jsonOutput, authScheme);
 
   // Parse --context and --request flags (supports inline JSON or @file.json)
   let context = {};
@@ -4047,6 +4317,7 @@ async function handleStoryboardStepCmd(args) {
     request,
     ...buildResolvedAuthOption({
       resolvedAuth,
+      resolvedAuthScheme,
       resolvedOauthTokens,
       resolvedOauthClient,
       resolvedOauthClientCredentials,
@@ -4584,10 +4855,17 @@ Save an agent URL under an alias in ~/.adcp/config.json so future commands
 can use the alias in place of the URL.
 
 AUTH METHODS (pick one):
-  Static bearer token:
+  Static bearer token (default):
     --auth <token>            Pre-issued bearer token
     --no-auth                 Agent requires no auth
 
+  HTTP Basic auth (RFC 7617, for gateways like Apigee/Kong/AWS API GW that
+  front the agent with a BasicAuthentication policy):
+    --auth <user:pass>        Credentials in 'user:pass' form
+    --auth-scheme basic       Required to switch from bearer to Basic. The
+                              username is checked for the RFC 7617 ban on
+                              ':', and both halves are checked for CR/LF/NUL.
+
 HEADERS (compose with any auth method):
     -H, --header K=V          Extra HTTP header on every request to this agent.
                               Repeatable. Persists in ~/.adcp/config.json.
@@ -4618,6 +4896,9 @@ EXAMPLES:
   # Static bearer (local dev)
   adcp --save-auth mine https://agent.example.com/mcp --auth AB12
 
+  # HTTP Basic (gateway-fronted agent — Apigee, Kong, AWS API GW)
+  adcp --save-auth mine https://agent.example.com/mcp --auth user:pass --auth-scheme basic
+
   # Browser OAuth
   adcp --save-auth mine https://agent.example.com/mcp --oauth
 
@@ -4656,6 +4937,7 @@ credential material — never sync or commit.
     // consume the next token; boolean flags consume only themselves.
     const valueFlags = new Set([
       '--auth',
+      '--auth-scheme',
       '--oauth-token-url',
       '--client-id',
       '--client-id-env',
@@ -4691,13 +4973,40 @@ credential material — never sync or commit.
         } else if (booleanFlags.has(tok)) {
           parsedFlags[tok] = true;
         } else {
-          positional.push(tok);
+          // Equals-form: `--auth-scheme=basic` (no space). The long-form
+          // valueFlags check above only matches the bare flag name; the
+          // equals form lands here. Mirror the parsing pattern used at the
+          // top-level parseAuthSchemeFlag so the two surfaces stay aligned.
+          const eqMatch = /^(--[a-z-]+)=(.+)$/i.exec(tok);
+          if (eqMatch && valueFlags.has(eqMatch[1])) {
+            parsedFlags[eqMatch[1]] = eqMatch[2];
+          } else {
+            positional.push(tok);
+          }
         }
       }
     }
     const savedHeaders = savedHeadersFromFlags.customHeaders;
 
     const providedAuthToken = parsedFlags['--auth'] ?? null;
+    // Honor `ADCP_AUTH_SCHEME` on the save path too — CI scripts that set it
+    // globally shouldn't have to re-pass the flag on every `adcp --save-auth`.
+    // The CLI flag wins on conflict (consistent with the runtime path).
+    const providedAuthScheme = parsedFlags['--auth-scheme'] ?? process.env.ADCP_AUTH_SCHEME ?? null;
+    if (providedAuthScheme !== null && providedAuthScheme !== 'bearer' && providedAuthScheme !== 'basic') {
+      const sourceLabel = parsedFlags['--auth-scheme'] !== undefined ? '--auth-scheme' : 'ADCP_AUTH_SCHEME env var';
+      console.error(`ERROR: ${sourceLabel} must be 'bearer' or 'basic', got: ${providedAuthScheme}\n`);
+      process.exit(2);
+    }
+    if (providedAuthScheme === 'basic' && providedAuthToken !== null) {
+      // Validate at register time so a typo (missing `:`) doesn't get persisted
+      // to disk and then surface as a confusing decode error on every later call.
+      decodeBasicCredentials(providedAuthToken, '--auth');
+    }
+    if (providedAuthScheme !== null && providedAuthToken === null) {
+      console.error('ERROR: --auth-scheme requires --auth (no token to interpret)\n');
+      process.exit(2);
+    }
     const noAuthFlag = parsedFlags['--no-auth'] === true;
     const oauthFlag = parsedFlags['--oauth'] === true;
     const dryRunFlag = parsedFlags['--dry-run'] === true;
@@ -5121,7 +5430,16 @@ credential material — never sync or commit.
     const hasAuthDecision = providedAuthToken !== null || noAuthFlag;
     const nonInteractive = url && hasAuthDecision;
 
-    await interactiveSetup(alias, url, protocol, providedAuthToken, nonInteractive, noAuthFlag, savedHeaders);
+    await interactiveSetup(
+      alias,
+      url,
+      protocol,
+      providedAuthToken,
+      nonInteractive,
+      noAuthFlag,
+      savedHeaders,
+      providedAuthScheme
+    );
     process.exit(0);
   }
 
@@ -5144,7 +5462,17 @@ credential material — never sync or commit.
         console.log(`    Protocol: ${agent.protocol}`);
       }
       if (agent.auth_token) {
-        console.log(`    Auth: token configured`);
+        if (agent.auth_scheme === 'basic') {
+          // For basic, show the username — it's already on disk in cleartext
+          // and seeing it makes the alias immediately recognizable (e.g. tells
+          // you which gateway tenant this alias talks to). Password is the
+          // sensitive half and stays hidden.
+          const colonIdx = agent.auth_token.indexOf(':');
+          const username = colonIdx > 0 ? agent.auth_token.slice(0, colonIdx) : '(malformed)';
+          console.log(`    Auth: HTTP Basic (user=${username})`);
+        } else {
+          console.log(`    Auth: bearer token configured`);
+        }
       }
       if (agent.oauth_client_credentials) {
         // Intentionally minimal: show only that CC is configured and the
@@ -5235,6 +5563,10 @@ credential material — never sync or commit.
   // Parse options first
   const authIndex = args.indexOf('--auth');
   let authToken = authIndex !== -1 ? args[authIndex + 1] : process.env.ADCP_AUTH_TOKEN;
+  // `--auth-scheme bearer|basic`. Default null → defer to saved alias's
+  // `auth_scheme`, then fall back to `bearer`. `--auth user:pass --auth-scheme
+  // basic` is the gateway-Basic shape (e.g. an Apigee BasicAuthentication policy).
+  let authScheme = parseAuthSchemeFlag(args);
   // adcp-client#1612: accept `--transport` as an alias for `--protocol`.
   // Hard-fail when the flag is present without a value, matching sites 1
   // and 2 — security review of #1619 flagged the silent-fallthrough as a
@@ -5275,6 +5607,7 @@ credential material — never sync or commit.
     arg =>
       !arg.startsWith('--') &&
       arg !== authToken && // Don't include the auth token value
+      arg !== authScheme && // Don't include the auth-scheme value
       arg !== protocolFlag && // Don't include the protocol value
       arg !== (timeoutIndex !== -1 ? args[timeoutIndex + 1] : null) && // Don't include timeout value
       !headerTokens.has(arg) // Drop -H and its KEY=VALUE payload
@@ -5331,6 +5664,12 @@ credential material — never sync or commit.
     if (!authToken) {
       authToken = getEffectiveAuthToken(savedAgent);
     }
+    // Honor the alias's saved scheme only when the caller didn't override
+    // it explicitly. Lets a basic-auth alias work without `--auth-scheme basic`
+    // on every invocation.
+    if (authScheme === null && savedAgent.auth_scheme) {
+      authScheme = savedAgent.auth_scheme;
+    }
 
     if (debug) {
       console.error(`DEBUG: Using saved agent '${firstArg}'`);
@@ -5397,7 +5736,14 @@ credential material — never sync or commit.
     console.error(`  Protocol: ${protocol}`);
     console.error(`  Agent URL: ${agentUrl}`);
     console.error(`  Tool: ${toolName || '(list tools)'}`);
-    console.error(`  Auth: ${authToken ? 'provided' : useOAuth ? 'oauth' : 'none'}`);
+    const authLabel = authToken
+      ? authScheme === 'basic'
+        ? 'basic (user:pass)'
+        : 'bearer'
+      : useOAuth
+        ? 'oauth'
+        : 'none';
+    console.error(`  Auth: ${authLabel}`);
     console.error(`  Payload: ${JSON.stringify(payload, null, 2)}`);
     console.error('');
   }
@@ -5432,9 +5778,47 @@ credential material — never sync or commit.
     }
   }
 
+  // Runtime mutex: `--auth-scheme basic` is incompatible with any OAuth shape
+  // (browser flow, refresh-token alias, or client credentials). The
+  // `--save-auth` flow catches this at register time, but a user invoking
+  // `adcp <oauth-alias> <tool> --auth user:pass --auth-scheme basic` would
+  // previously have the basic credential silently dropped because the gating
+  // logic below excludes basic when any OAuth material is present. Fail
+  // closed instead — better a clear error than a credential silently ignored.
+  if (authScheme === 'basic' && (useOAuth || agentOAuthClientCredentials || agentOAuthTokens)) {
+    console.error(
+      '\n❌ ERROR: --auth-scheme basic cannot be combined with --oauth or with an alias that has OAuth tokens / client credentials.\n' +
+        '   The agent is already configured for OAuth — pick one auth method, not both.\n'
+    );
+    process.exit(2);
+  }
+
   // Merge saved-alias headers (per-agent routing context, e.g. x-adcp-tenant)
   // with `-H KEY=VALUE` flags from the current invocation. CLI wins on conflict.
-  const mergedHeaders = mergeHeaders(savedAgent && savedAgent.headers, cliHeaders);
+  let mergedHeaders = mergeHeaders(savedAgent && savedAgent.headers, cliHeaders);
+
+  // Basic auth path: gateways like Apigee/Kong/AWS API GW with a
+  // BasicAuthentication policy speak RFC 7617 (`Authorization: Basic
+  // <base64(user:pass)>`), not OAuth bearer. We inject the encoded header
+  // AFTER `mergeHeaders` runs so the reserved-key filter doesn't strip it.
+  // The protocol layer (`src/lib/protocols/mcp.ts:475-477`,
+  // `src/lib/protocols/a2a.ts:283-292`) spreads `customHeaders` before the
+  // SDK-supplied Authorization, so suppressing `auth_token` here lets our
+  // injected Basic header reach the wire intact.
+  const useBasicAuth = authScheme === 'basic' && authToken;
+  if (useBasicAuth) {
+    // Helper extraction protects the invariant: this MUST run after
+    // mergeHeaders() so the reserved-key filter doesn't strip the injection.
+    // See `injectBasicAuthHeader`'s docstring for the full rationale.
+    mergedHeaders = injectBasicAuthHeader(mergedHeaders, authToken);
+  }
+
+  // Advisory warning: surface ADCP_AUTH_SCHEME=basic when no token resolved
+  // (otherwise the env var is silently no-op and adopters wonder why their
+  // Basic gateway keeps 401ing). Only fires in the env-set-but-not-applied
+  // case — the inverse (token-without-scheme → silent bearer) is the safe
+  // direction.
+  maybeWarnAuthSchemeIneffective(authToken, authScheme || 'bearer');
 
   // Create agent config
   const agentConfig = {
@@ -5442,7 +5826,11 @@ credential material — never sync or commit.
     name: 'CLI Agent',
     agent_uri: agentUrl,
     protocol: protocol,
-    ...(authToken && !useOAuth && !agentOAuthClientCredentials && { auth_token: authToken, requiresAuth: true }),
+    ...(authToken &&
+      !useOAuth &&
+      !agentOAuthClientCredentials &&
+      !useBasicAuth && { auth_token: authToken, requiresAuth: true }),
+    ...(useBasicAuth && { requiresAuth: true }),
     ...(agentOAuthTokens && { oauth_tokens: agentOAuthTokens }),
     ...(agentOAuthClient && { oauth_client: agentOAuthClient }),
     ...(agentOAuthClientCredentials && { oauth_client_credentials: agentOAuthClientCredentials }),
@@ -5963,14 +6351,28 @@ credential material — never sync or commit.
     // `NeedsAuthorizationError` is the richer form (already extended from
     // AuthenticationRequiredError); the string-match branches cover older
     // error shapes from the MCP SDK and other 401 paths.
+    // `Authentication required` matches the plain `AuthenticationRequiredError`
+    // (thrown when the SDK got 401 but couldn't walk OAuth metadata) — that's
+    // the exact shape a Basic-fronted gateway produces, so it's critical the
+    // Basic-hint path catches it.
     const isUnauthorized =
       error instanceof NeedsAuthorizationError ||
       error.name === 'UnauthorizedError' ||
+      error.name === 'AuthenticationRequiredError' ||
       error.message?.toLowerCase().includes('unauthorized') ||
+      error.message?.toLowerCase().includes('authentication required') ||
       error.message?.includes('401');
 
     if (isUnauthorized && protocol === 'mcp' && !useOAuth && !authToken) {
       console.log('\n🔐 Server requires authentication.');
+      // Some agents sit behind an API gateway with a BasicAuthentication policy
+      // (Apigee, Kong, AWS API GW, nginx auth_basic). OAuth won't succeed
+      // against those gateways no matter how the browser flow goes — surface
+      // the alternative before opening the browser so a Basic-fronted adopter
+      // doesn't bounce through a doomed OAuth handshake first.
+      console.log(
+        'If your agent is fronted by an HTTP-Basic gateway, retry with: --auth <user:pass> --auth-scheme basic'
+      );
       console.log('Starting OAuth authentication...\n');
 
       // Run OAuth flow automatically