@adcp/sdk 14.4.0 → 15.2.0

package/bin/adcp-grade.js

@@ -45,7 +45,25 @@ Options:
                              JSON-RPC tools/call envelope and posts to the
                              agent's MCP mount (see #612); \`raw\` posts to
                              per-operation AdCP endpoints (REST-binding agents);
-                             \`a2a\` signs the official A2A client's request.
+                             \`a2a\` signs the official A2A client's request
+                             and also grades the A2A operation-resolution
+                             vectors (adcp#7945): required_for must be
+                             enforced against the operation named by the
+                             invocation DataPart's \`skill\`, not the JSON-RPC
+                             method. Vector ids are prefixed a2a/. Tiers:
+                             contradiction-resolution (MUST in 3.2) and
+                             hardening (SHOULD in 3.2.x, MUST from 3.3). The
+                             signed create_media_buy vectors need
+                             --allow-live-side-effects (or a sandbox
+                             contract). If the compliance bundle carries no
+                             A2A vectors the run reports them unavailable.
+  --required-for <op[,op...]>
+                             Agent's request_signing.required_for. Skips
+                             vectors that assert an operation the agent does
+                             not require (capability_profile_mismatch).
+  --protocol-methods-required-for <m[,m...]>
+                             Agent's request_signing.protocol_methods_required_for
+                             (e.g. SendMessage). Gates A2A negative/007.
   --timeout <ms>             Per-probe timeout (default 10000)
   --json                     Emit the full GradeReport as JSON
   -h, --help                 Show this help
@@ -54,6 +72,9 @@ Environment:
   ADCP_GRADE_INITIALIZE_AUTHORIZATION
                              Authorization header used only for the MCP
                              initialize lifecycle (kept out of process argv).
+  ADCP_A2A_VECTORS_DIR       Directory with the A2A operation-resolution
+                             vectors (positive/ and negative/), overriding the
+                             compliance bundle. For bundles that predate them.
 
 Exit code:
   0   all graded vectors passed (skipped vectors don't count as failures)
@@ -202,6 +223,12 @@ async function runRequestSigningGrader(args) {
         options.signingProfileVersion = profile;
         break;
       }
+      case '--required-for':
+        options.agentRequiredFor = parseVectorList(args[++i], '--required-for');
+        break;
+      case '--protocol-methods-required-for':
+        options.agentProtocolMethodsRequiredFor = parseVectorList(args[++i], '--protocol-methods-required-for');
+        break;
       case '--allow-live-side-effects':
         options.allowLiveSideEffects = true;
         break;
@@ -470,6 +497,7 @@ function printHumanReport(report, options = {}) {
     `${report.passed_count} passed, ${report.failed_count} failed, ${report.skipped_count} skipped — total ${report.total_duration_ms}ms`
   );
   console.log(`Overall: ${report.passed ? 'PASS' : 'FAIL'}`);
+  printA2aOperationResolutionSummary(report.a2a_operation_resolution);
   // Only hint on an EXPLICIT --transport raw run — mcp is the default now,
   // so an unset transport already grades over MCP and the raw→mcp retry
   // hint would misdirect (if mcp mode fails everywhere, it's a different
@@ -484,6 +512,22 @@ function printHumanReport(report, options = {}) {
   console.log();
 }
 
+function printA2aOperationResolutionSummary(summary) {
+  if (!summary) return;
+  console.log();
+  if (!summary.vectors_available) {
+    console.log(`⚠  A2A operation-resolution: ${summary.message}. required_for over A2A was NOT graded.`);
+    return;
+  }
+  const t = summary.tiers;
+  const line = (label, tier) =>
+    `  ${label}: ${tier.passed} passed, ${tier.failed} failed, ${tier.skipped} skipped` +
+    (tier.failed_vectors.length ? ` (failed: ${tier.failed_vectors.join(', ')})` : '');
+  console.log(`A2A operation-resolution vectors (source: ${summary.source}):`);
+  console.log(line('contradiction-resolution (MUST in 3.2)', t['contradiction-resolution']));
+  console.log(line('hardening (SHOULD in 3.2.x, MUST from 3.3)', t.hardening));
+}
+
 /**
  * Heuristic: if the grader ran in `raw` mode (explicit --transport raw —
  * mcp is the default) and every non-skipped vector
@@ -516,7 +560,7 @@ function formatRow(r) {
     : r.passed
       ? `${r.http_status}${r.actual_error_code ? ` ${r.actual_error_code}` : ''}`
       : (r.diagnostic ?? 'see report');
-  return { id, status, detail };
+  return { id, status, detail: r.tier && !r.skipped ? `[${r.tier}] ${detail}` : detail };
 }
 
 module.exports = { handleGradeCommand };

package/bin/adcp.js

@@ -1966,7 +1966,9 @@ COMMANDS:
   doctor [options]            Check project secrets, SDK drift, and migrations
   storyboard <subcommand>     Test agent flows (run, list, show, step)
   specialism <subcommand>     Inspect a compliance specialism (list, show)
-  grade <subject> <url>       Conformance graders (e.g. request-signing)
+  grade <subject> <url>       Conformance graders (e.g. request-signing; with
+                              --transport a2a it also grades the A2A
+                              operation-resolution vectors)
   fuzz <url>                  Property-based conformance fuzzing against schemas
   resolve <agent-url>         Walk the brand_json_url discovery chain
                               (capabilities -> brand.json -> JWKS) and print
@@ -2191,7 +2193,10 @@ REQUEST-SIGNING VECTOR OPTIONS (signed_requests storyboard):
                                   discovery. Pass raw for agents that
                                   expose AdCP tools as per-operation HTTP
                                   endpoints. Mirrors
-                                  \`adcp grade request-signing --transport\`.
+                                  \`adcp grade request-signing --transport\`,
+                                  which with a2a additionally grades the A2A
+                                  operation-resolution vectors (required_for
+                                  keyed on the DataPart skill, adcp#7945).
   --signing-skip-vectors IDS      Comma-separated vector ids to skip (graded
                                   operator_skip), e.g.
                                   025-jwk-alg-crv-mismatch. Unknown ids are
@@ -6659,7 +6664,12 @@ credential material — never sync or commit.
     }
 
     const agentConfig = getAgent(alias);
-    if (!agentConfig.oauth_tokens) {
+    if (
+      !agentConfig.oauth_tokens &&
+      !agentConfig.oauth_client &&
+      !agentConfig.oauth_code_verifier &&
+      !agentConfig.oauth_discovery_state
+    ) {
       console.log(`\nAgent '${alias}' has no OAuth tokens to clear.\n`);
       process.exit(0);
     }

package/dist/lib/auth/oauth/ClientCredentialsFlow.js

@@ -247,7 +247,10 @@ async function ensureClientCredentialsTokens(agent, options = {}) {
       });
       agent.oauth_tokens = tokens;
       if (options.storage) {
-        await options.storage.saveAgent(agent);
+        const refreshedAgent = { ...agent };
+        delete refreshedAgent.oauth_code_verifier;
+        delete refreshedAgent.oauth_discovery_state;
+        await options.storage.saveAgent(refreshedAgent);
       }
       return tokens;
     } finally {

package/dist/lib/auth/oauth/ClientCredentialsFlow.mjs

@@ -222,7 +222,10 @@ async function ensureClientCredentialsTokens(agent, options = {}) {
       });
       agent.oauth_tokens = tokens;
       if (options.storage) {
-        await options.storage.saveAgent(agent);
+        const refreshedAgent = { ...agent };
+        delete refreshedAgent.oauth_code_verifier;
+        delete refreshedAgent.oauth_discovery_state;
+        await options.storage.saveAgent(refreshedAgent);
       }
       return tokens;
     } finally {

package/dist/lib/auth/oauth/MCPOAuthProvider.d.mts

@@ -20,13 +20,15 @@ export declare function assertLegacyOAuthSdk(): void;
  *   name: 'My Agent',
  *   agent_uri: 'https://agent.example.com/mcp',
  *   protocol: 'mcp',
- *   // OAuth tokens stored here after auth flow
- *   oauth_tokens: { access_token: '...', refresh_token: '...' }
+ *   // A fresh interactive flow saves issuer-bound credentials afterward.
  * };
  *
+ * const flowHandler = new CLIFlowHandler();
  * const provider = new MCPOAuthProvider({
  *   agent,
- *   flowHandler: new CLIFlowHandler(),
+ *   flowHandler,
+ *   clientMetadata: { ...DEFAULT_CLIENT_METADATA, redirect_uris: [flowHandler.getRedirectUrl().toString()] },
+ *   allowInteractiveAuthorization: true,
  *   storage: myConfigStorage  // Optional: persists tokens
  * });
  *
@@ -42,6 +44,8 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     private readonly _clientMetadata;
     private readonly allowHttp;
     private readonly configuredResourceOverride?;
+    private readonly allowInteractiveAuthorization;
+    private pendingDiscoveryState?;
     constructor(config: OAuthProviderConfig);
     /**
      * Create a provider for CLI usage
@@ -73,7 +77,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /**
      * Load client information from agent config
      */
-    clientInformation(): Promise<OAuthClientInformation | undefined>;
+    clientInformation(ctx?: {
+        issuer: string;
+    }): Promise<OAuthClientInformation | undefined>;
     /**
      * Save client information after dynamic registration
      */
@@ -81,7 +87,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /**
      * Load existing tokens from agent config
      */
-    tokens(): Promise<OAuthTokens | undefined>;
+    tokens(ctx?: {
+        issuer: string;
+    }): Promise<OAuthTokens | undefined>;
     /**
      * Save tokens after authorization
      * Also cleans up the temporary code verifier
@@ -94,6 +102,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /** Persist the authorization-server identity across the callback leg. */
     saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
     discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    private validateDiscoveryState;
+    private checkIssuerContext;
+    private ownerReauthorizationRequired;
     /**
      * Save PKCE code verifier
      */
@@ -108,9 +119,11 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
      * Invalidate credentials when server indicates they're invalid
      */
     invalidateCredentials(scope: Parameters<NonNullable<OAuthClientProvider['invalidateCredentials']>>[0]): Promise<void>;
+    private clearCredentials;
     /**
-     * Persist agent config to storage if configured
+     * Persist a credential update without modifying independent browser state.
      */
+    private persistCredentials;
     private persistAgent;
     /**
      * Wait for the OAuth callback

package/dist/lib/auth/oauth/MCPOAuthProvider.d.ts

@@ -20,13 +20,15 @@ export declare function assertLegacyOAuthSdk(): void;
  *   name: 'My Agent',
  *   agent_uri: 'https://agent.example.com/mcp',
  *   protocol: 'mcp',
- *   // OAuth tokens stored here after auth flow
- *   oauth_tokens: { access_token: '...', refresh_token: '...' }
+ *   // A fresh interactive flow saves issuer-bound credentials afterward.
  * };
  *
+ * const flowHandler = new CLIFlowHandler();
  * const provider = new MCPOAuthProvider({
  *   agent,
- *   flowHandler: new CLIFlowHandler(),
+ *   flowHandler,
+ *   clientMetadata: { ...DEFAULT_CLIENT_METADATA, redirect_uris: [flowHandler.getRedirectUrl().toString()] },
+ *   allowInteractiveAuthorization: true,
  *   storage: myConfigStorage  // Optional: persists tokens
  * });
  *
@@ -42,6 +44,8 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     private readonly _clientMetadata;
     private readonly allowHttp;
     private readonly configuredResourceOverride?;
+    private readonly allowInteractiveAuthorization;
+    private pendingDiscoveryState?;
     constructor(config: OAuthProviderConfig);
     /**
      * Create a provider for CLI usage
@@ -73,7 +77,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /**
      * Load client information from agent config
      */
-    clientInformation(): Promise<OAuthClientInformation | undefined>;
+    clientInformation(ctx?: {
+        issuer: string;
+    }): Promise<OAuthClientInformation | undefined>;
     /**
      * Save client information after dynamic registration
      */
@@ -81,7 +87,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /**
      * Load existing tokens from agent config
      */
-    tokens(): Promise<OAuthTokens | undefined>;
+    tokens(ctx?: {
+        issuer: string;
+    }): Promise<OAuthTokens | undefined>;
     /**
      * Save tokens after authorization
      * Also cleans up the temporary code verifier
@@ -94,6 +102,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /** Persist the authorization-server identity across the callback leg. */
     saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
     discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    private validateDiscoveryState;
+    private checkIssuerContext;
+    private ownerReauthorizationRequired;
     /**
      * Save PKCE code verifier
      */
@@ -108,9 +119,11 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
      * Invalidate credentials when server indicates they're invalid
      */
     invalidateCredentials(scope: Parameters<NonNullable<OAuthClientProvider['invalidateCredentials']>>[0]): Promise<void>;
+    private clearCredentials;
     /**
-     * Persist agent config to storage if configured
+     * Persist a credential update without modifying independent browser state.
      */
+    private persistCredentials;
     private persistAgent;
     /**
      * Wait for the OAuth callback

package/dist/lib/auth/oauth/MCPOAuthProvider.js

@@ -59,6 +59,8 @@ class MCPOAuthProvider {
   _clientMetadata;
   allowHttp;
   configuredResourceOverride;
+  allowInteractiveAuthorization;
+  pendingDiscoveryState;
   constructor(config) {
     this.agent = config.agent;
     this.storage = config.storage;
@@ -66,6 +68,7 @@ class MCPOAuthProvider {
     this._clientMetadata = config.clientMetadata;
     this.allowHttp = config.allowHttp === true;
     this.configuredResourceOverride = config.resourceOverride;
+    this.allowInteractiveAuthorization = config.allowInteractiveAuthorization === true;
   }
   /**
    * Create a provider for CLI usage
@@ -82,7 +85,8 @@ class MCPOAuthProvider {
       storage,
       clientMetadata,
       allowHttp: options?.allowHttp,
-      resourceOverride: options?.resourceOverride
+      resourceOverride: options?.resourceOverride,
+      allowInteractiveAuthorization: true
     });
   }
   // ========================================
@@ -123,7 +127,11 @@ class MCPOAuthProvider {
   /**
    * Load client information from agent config
    */
-  async clientInformation() {
+  async clientInformation(ctx) {
+    const issuer = this.checkIssuerContext(ctx);
+    if (issuer && !this.agent.oauth_client && !this.allowInteractiveAuthorization) {
+      throw this.ownerReauthorizationRequired();
+    }
     if (this.agent.oauth_client) {
       if (this.agent.oauth_client.client_secret) assertLegacyOAuthSdk();
       (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_client, void 0, !!this.agent.oauth_client.client_secret);
@@ -136,12 +144,13 @@ class MCPOAuthProvider {
    */
   async saveClientInformation(clientInfo) {
     this.agent.oauth_client = (0, import_types.fromMCPClientInfo)(clientInfo);
-    await this.persistAgent();
+    await this.persistCredentials();
   }
   /**
    * Load existing tokens from agent config
    */
-  async tokens() {
+  async tokens(ctx) {
+    this.checkIssuerContext(ctx);
     if (this.agent.oauth_tokens) {
       if (this.agent.oauth_tokens.refresh_token) assertLegacyOAuthSdk();
       (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_tokens, void 0, !!this.agent.oauth_tokens.refresh_token);
@@ -155,14 +164,18 @@ class MCPOAuthProvider {
    */
   async saveTokens(tokens) {
     this.agent.oauth_tokens = (0, import_types.fromMCPTokens)(tokens);
-    delete this.agent.oauth_code_verifier;
-    delete this.agent.oauth_discovery_state;
-    await this.persistAgent();
+    if (this.allowInteractiveAuthorization) {
+      this.agent.oauth_code_verifier = void 0;
+      this.agent.oauth_discovery_state = void 0;
+    }
+    this.pendingDiscoveryState = void 0;
+    await this.persistCredentials();
   }
   /**
    * Redirect user to authorization URL
    */
   async redirectToAuthorization(authorizationUrl) {
+    if (!this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired("interactive_required");
     try {
       await this.flowHandler.redirectToAuthorization(authorizationUrl);
     } catch (error) {
@@ -172,23 +185,51 @@ class MCPOAuthProvider {
   }
   /** Persist the authorization-server identity across the callback leg. */
   async saveDiscoveryState(state) {
-    const issuer = String(state.authorizationServerUrl);
-    if (this.agent.oauth_tokens?.refresh_token) {
-      (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_tokens, issuer, true);
-    }
-    if (this.agent.oauth_client?.client_secret) {
-      (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_client, issuer, true);
+    this.validateDiscoveryState(state);
+    if (!this.agent.oauth_client && !this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired();
+    this.pendingDiscoveryState = structuredClone(state);
+    if (this.allowInteractiveAuthorization) {
+      this.agent.oauth_discovery_state = structuredClone(state);
+      await this.persistAgent();
     }
-    this.agent.oauth_discovery_state = state;
-    await this.persistAgent();
   }
   async discoveryState() {
-    return this.agent.oauth_code_verifier ? this.agent.oauth_discovery_state : void 0;
+    if (!this.allowInteractiveAuthorization) return void 0;
+    if (!this.agent.oauth_code_verifier) return void 0;
+    const state = this.pendingDiscoveryState ?? this.agent.oauth_discovery_state;
+    if (!state) return void 0;
+    this.validateDiscoveryState(state);
+    this.pendingDiscoveryState = structuredClone(state);
+    return structuredClone(state);
+  }
+  validateDiscoveryState(state) {
+    (0, import_types.assertOAuthServerIssuer)(state.authorizationServerMetadata, String(state.authorizationServerUrl));
+    this.checkIssuerContext({ issuer: String(state.authorizationServerUrl) });
+  }
+  checkIssuerContext(ctx) {
+    const issuer = ctx?.issuer ?? this.pendingDiscoveryState?.authorizationServerUrl;
+    if (issuer !== void 0) {
+      if (this.agent.oauth_tokens) {
+        (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_tokens, issuer, !!this.agent.oauth_tokens.refresh_token);
+      }
+      if (this.agent.oauth_client) {
+        (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_client, issuer, !!this.agent.oauth_client.client_secret);
+      }
+    }
+    return issuer;
+  }
+  ownerReauthorizationRequired(code = "owner_reauthorization_required") {
+    return new import_types.OAuthError(
+      "OAuth owner reauthorization is required; this provider will not automatically clear credentials or register a new client. CLI: adcp <alias> --clear-oauth, then adcp <alias> --oauth.",
+      code,
+      this.agent.id
+    );
   }
   /**
    * Save PKCE code verifier
    */
   async saveCodeVerifier(codeVerifier) {
+    if (!this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired();
     this.agent.oauth_code_verifier = codeVerifier;
     await this.persistAgent();
   }
@@ -198,6 +239,7 @@ class MCPOAuthProvider {
    * retrieves it here during token exchange.
    */
   async codeVerifier() {
+    if (!this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired();
     if (!this.agent.oauth_code_verifier) {
       throw new Error(
         "No PKCE code verifier found. The OAuth flow may have been interrupted or the agent config was modified. Please try authenticating again."
@@ -209,26 +251,40 @@ class MCPOAuthProvider {
    * Invalidate credentials when server indicates they're invalid
    */
   async invalidateCredentials(scope) {
+    if (!this.allowInteractiveAuthorization && (scope === "discovery" || scope === "verifier")) {
+      this.pendingDiscoveryState = void 0;
+      return;
+    }
+    if (!this.allowInteractiveAuthorization && (scope === "all" || scope === "client" || scope === "tokens")) {
+      throw this.ownerReauthorizationRequired();
+    }
+    await this.clearCredentials(scope);
+  }
+  async clearCredentials(scope) {
     switch (scope) {
       case "all":
-        delete this.agent.oauth_discovery_state;
-        delete this.agent.oauth_tokens;
-        delete this.agent.oauth_client;
-        delete this.agent.oauth_code_verifier;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
+        this.agent.oauth_tokens = void 0;
+        this.agent.oauth_client = void 0;
+        this.agent.oauth_code_verifier = void 0;
         break;
       case "tokens":
-        delete this.agent.oauth_tokens;
+        this.agent.oauth_tokens = void 0;
         break;
       case "client":
-        delete this.agent.oauth_discovery_state;
-        delete this.agent.oauth_client;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
+        this.agent.oauth_client = void 0;
         break;
       case "discovery":
-        delete this.agent.oauth_discovery_state;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
         break;
       case "verifier":
-        delete this.agent.oauth_discovery_state;
-        delete this.agent.oauth_code_verifier;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
+        this.agent.oauth_code_verifier = void 0;
         break;
     }
     await this.persistAgent();
@@ -237,11 +293,20 @@ class MCPOAuthProvider {
   // Additional methods
   // ========================================
   /**
-   * Persist agent config to storage if configured
+   * Persist a credential update without modifying independent browser state.
    */
-  async persistAgent() {
+  async persistCredentials() {
+    let savedAgent = this.agent;
+    if (!this.allowInteractiveAuthorization) {
+      savedAgent = { ...this.agent };
+      delete savedAgent.oauth_code_verifier;
+      delete savedAgent.oauth_discovery_state;
+    }
+    await this.persistAgent(savedAgent);
+  }
+  async persistAgent(agent = this.agent) {
     if (this.storage) {
-      await this.storage.saveAgent(this.agent);
+      await this.storage.saveAgent(agent);
     }
   }
   /**
@@ -283,7 +348,7 @@ class MCPOAuthProvider {
    * Clear all OAuth data for this agent
    */
   async clearAuth() {
-    await this.invalidateCredentials("all");
+    await this.clearCredentials("all");
   }
   /**
    * Get the agent config this provider manages