@adcp/sdk 17.0.0-beta.25 → 17.0.0-beta.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/dist/lib/discovery/agent-directory.d.mts +10 -3
  2. package/dist/lib/discovery/agent-directory.d.ts +10 -3
  3. package/dist/lib/discovery/property-crawler.d.mts +11 -0
  4. package/dist/lib/discovery/property-crawler.d.ts +11 -0
  5. package/dist/lib/discovery/property-crawler.js +15 -2
  6. package/dist/lib/discovery/property-crawler.mjs +15 -2
  7. package/dist/lib/discovery/resolve-agent-properties.d.mts +170 -8
  8. package/dist/lib/discovery/resolve-agent-properties.d.ts +170 -8
  9. package/dist/lib/discovery/resolve-agent-properties.js +155 -14
  10. package/dist/lib/discovery/resolve-agent-properties.mjs +151 -13
  11. package/dist/lib/discovery/types.d.mts +14 -0
  12. package/dist/lib/discovery/types.d.ts +14 -0
  13. package/dist/lib/discovery/validate-adagents.d.mts +7 -0
  14. package/dist/lib/discovery/validate-adagents.d.ts +7 -0
  15. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  16. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  17. package/dist/lib/entrypoints/discovery.js +6 -0
  18. package/dist/lib/entrypoints/discovery.mjs +7 -1
  19. package/dist/lib/index.d.mts +1 -1
  20. package/dist/lib/index.d.ts +1 -1
  21. package/dist/lib/index.js +6 -0
  22. package/dist/lib/index.mjs +7 -1
  23. package/dist/lib/registry/types.generated.d.ts +5 -5
  24. package/dist/lib/supply-path/validation.d.mts +8 -0
  25. package/dist/lib/supply-path/validation.d.ts +8 -0
  26. package/dist/lib/testing/compliance/comply.js +9 -2
  27. package/dist/lib/testing/compliance/comply.mjs +11 -3
  28. package/dist/lib/testing/storyboard/index.d.mts +1 -1
  29. package/dist/lib/testing/storyboard/index.d.ts +1 -1
  30. package/dist/lib/testing/storyboard/index.js +6 -0
  31. package/dist/lib/testing/storyboard/index.mjs +6 -0
  32. package/dist/lib/testing/storyboard/loader.js +52 -28
  33. package/dist/lib/testing/storyboard/loader.mjs +52 -28
  34. package/dist/lib/testing/storyboard/runner.d.mts +24 -1
  35. package/dist/lib/testing/storyboard/runner.d.ts +24 -1
  36. package/dist/lib/testing/storyboard/runner.js +75 -7
  37. package/dist/lib/testing/storyboard/runner.mjs +72 -7
  38. package/dist/lib/testing/storyboard/types.d.mts +51 -6
  39. package/dist/lib/testing/storyboard/types.d.ts +51 -6
  40. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  41. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  42. package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
  43. package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
  44. package/dist/lib/version.d.mts +3 -3
  45. package/dist/lib/version.d.ts +3 -3
  46. package/dist/lib/version.js +3 -3
  47. package/dist/lib/version.mjs +3 -3
  48. package/docs/TYPE-SUMMARY.md +1 -1
  49. package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
  50. package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
  51. package/docs/llms.txt +1 -1
  52. package/docs/migration-14.x-rc-worksheet.md +4 -4
  53. package/docs/migration-16-to-17.md +31 -0
  54. package/docs/migration-agent-resolution-3.3.md +18 -0
  55. package/package.json +1 -1
@@ -51,9 +51,16 @@ export interface DirectoryPublisherEntry {
51
51
  */
52
52
  properties_total: number;
53
53
  /**
54
- * Whether the publisher's adagents.json entry for this agent pins
55
- * `signing_keys[]`. When true, signed responses MUST verify against
56
- * the pinned key set regardless of the agent's own JWKS.
54
+ * Whether the publisher's adagents.json pins `signing_keys[]` for this
55
+ * agent: true only when every `authorized_agents[]` entry that matches the
56
+ * agent carries `signing_keys` (adcontextprotocol/adcp#9016). One matching
57
+ * entry without them, such as an unpinned origin-only entry beside a pinned
58
+ * full-URL entry, leaves the agent unpinned. When true, the agent's
59
+ * sell-side signatures about this publisher's inventory are accepted only
60
+ * with a key in both the pin and the agent's own JWKS. This is a
61
+ * scope-agnostic summary (entries outside their effective window are
62
+ * ignored); a verifier computes the pin per message scope with
63
+ * `resolvePublisherSigningKeyPin`, so a pin can apply where this is false.
57
64
  */
58
65
  signing_keys_pinned?: boolean;
59
66
  status: DirectoryPublisherStatus;
@@ -51,9 +51,16 @@ export interface DirectoryPublisherEntry {
51
51
  */
52
52
  properties_total: number;
53
53
  /**
54
- * Whether the publisher's adagents.json entry for this agent pins
55
- * `signing_keys[]`. When true, signed responses MUST verify against
56
- * the pinned key set regardless of the agent's own JWKS.
54
+ * Whether the publisher's adagents.json pins `signing_keys[]` for this
55
+ * agent: true only when every `authorized_agents[]` entry that matches the
56
+ * agent carries `signing_keys` (adcontextprotocol/adcp#9016). One matching
57
+ * entry without them, such as an unpinned origin-only entry beside a pinned
58
+ * full-URL entry, leaves the agent unpinned. When true, the agent's
59
+ * sell-side signatures about this publisher's inventory are accepted only
60
+ * with a key in both the pin and the agent's own JWKS. This is a
61
+ * scope-agnostic summary (entries outside their effective window are
62
+ * ignored); a verifier computes the pin per message scope with
63
+ * `resolvePublisherSigningKeyPin`, so a pin can apply where this is false.
57
64
  */
58
65
  signing_keys_pinned?: boolean;
59
66
  status: DirectoryPublisherStatus;
@@ -33,10 +33,21 @@ export interface PropertyCrawlerConfig {
33
33
  /** Custom identifier for outbound requests. Used as User-Agent for protocol
34
34
  * calls to agents and included in the From header for direct property fetches. */
35
35
  userAgent?: string;
36
+ /**
37
+ * AdCP release the crawler targets. Passed to each agent's client and used
38
+ * to match the agent against `authorized_agents[].url` when the agent's
39
+ * capabilities response does not report the release it served. Defaults to
40
+ * the SDK's pinned `ADCP_VERSION`. At 3.3 or later an origin-only entry
41
+ * authorizes the agent at any path on that origin (adcp#8862).
42
+ */
43
+ adcpVersion?: string;
36
44
  }
37
45
  export declare class PropertyCrawler {
38
46
  private logger;
39
47
  private userAgent?;
48
+ private adcpVersion?;
49
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
50
+ private servedVersions;
40
51
  constructor(config?: PropertyCrawlerConfig);
41
52
  /**
42
53
  * Crawl multiple agents to discover their publisher domains and properties
@@ -33,10 +33,21 @@ export interface PropertyCrawlerConfig {
33
33
  /** Custom identifier for outbound requests. Used as User-Agent for protocol
34
34
  * calls to agents and included in the From header for direct property fetches. */
35
35
  userAgent?: string;
36
+ /**
37
+ * AdCP release the crawler targets. Passed to each agent's client and used
38
+ * to match the agent against `authorized_agents[].url` when the agent's
39
+ * capabilities response does not report the release it served. Defaults to
40
+ * the SDK's pinned `ADCP_VERSION`. At 3.3 or later an origin-only entry
41
+ * authorizes the agent at any path on that origin (adcp#8862).
42
+ */
43
+ adcpVersion?: string;
36
44
  }
37
45
  export declare class PropertyCrawler {
38
46
  private logger;
39
47
  private userAgent?;
48
+ private adcpVersion?;
49
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
50
+ private servedVersions;
40
51
  constructor(config?: PropertyCrawlerConfig);
41
52
  /**
42
53
  * Crawl multiple agents to discover their publisher domains and properties
@@ -29,11 +29,15 @@ var import_validate_user_agent = require('../utils/validate-user-agent.js');
29
29
  var import_ssrf_fetch = require('../net/ssrf-fetch.js');
30
30
  var import_probe_policy = require('../utils/probe-policy.js');
31
31
  var import_resolve_agent_properties = require('./resolve-agent-properties.js');
32
+ var import_adcp_version_config = require('../utils/adcp-version-config.js');
32
33
  var import_adagents_redirects = require('./adagents-redirects.js');
33
34
  const MAX_ADAGENTS_BODY_BYTES = 256 * 1024;
34
35
  class PropertyCrawler {
35
36
  logger;
36
37
  userAgent;
38
+ adcpVersion;
39
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
40
+ servedVersions = /* @__PURE__ */ new Map();
37
41
  constructor(config) {
38
42
  this.logger = (0, import_logger.createLogger)({
39
43
  level: config?.logLevel || "warn"
@@ -42,6 +46,9 @@ class PropertyCrawler {
42
46
  (0, import_validate_user_agent.validateUserAgent)(config.userAgent);
43
47
  }
44
48
  this.userAgent = config?.userAgent;
49
+ if (config?.adcpVersion !== void 0) {
50
+ this.adcpVersion = (0, import_adcp_version_config.resolveAdcpVersion)(config.adcpVersion);
51
+ }
45
52
  }
46
53
  /**
47
54
  * Crawl multiple agents to discover their publisher domains and properties
@@ -57,6 +64,7 @@ class PropertyCrawler {
57
64
  };
58
65
  const index = (0, import_property_index.getPropertyIndex)();
59
66
  const allPublisherDomains = /* @__PURE__ */ new Set();
67
+ this.servedVersions.clear();
60
68
  for (const agentInfo of agents) {
61
69
  try {
62
70
  const domains = await this.crawlAgent(agentInfo);
@@ -95,7 +103,9 @@ class PropertyCrawler {
95
103
  for (const agentUrl of claimingAgents) {
96
104
  let attributable;
97
105
  if (adAgentsFile) {
98
- const scope = (0, import_resolve_agent_properties.resolveAgentProperties)(adAgentsFile, agentUrl);
106
+ const scope = (0, import_resolve_agent_properties.resolveAgentProperties)(adAgentsFile, agentUrl, {
107
+ adcpVersion: this.servedVersions.get(agentUrl) ?? this.adcpVersion
108
+ });
99
109
  attributable = scope.properties;
100
110
  } else {
101
111
  attributable = properties;
@@ -120,10 +130,13 @@ class PropertyCrawler {
120
130
  protocol: agentInfo.protocol || "mcp",
121
131
  ...agentInfo.auth_token && { auth_token: agentInfo.auth_token }
122
132
  },
123
- { userAgent: this.userAgent }
133
+ { userAgent: this.userAgent, ...this.adcpVersion !== void 0 && { adcpVersion: this.adcpVersion } }
124
134
  );
125
135
  try {
126
136
  const capabilities = await client.getCapabilities();
137
+ if (capabilities.servedVersion) {
138
+ this.servedVersions.set(agentInfo.agent_url, capabilities.servedVersion);
139
+ }
127
140
  if (!capabilities.publisherDomains) {
128
141
  return [];
129
142
  }
@@ -6,11 +6,15 @@ import { validateUserAgent } from "../utils/validate-user-agent.mjs";
6
6
  import { SsrfRefusedError, SSRF_TRANSIENT_CODES, decodeBodyAsJsonOrText } from "../net/ssrf-fetch.mjs";
7
7
  import { isInternalProbesAllowed } from "../utils/probe-policy.mjs";
8
8
  import { resolveAgentProperties } from "./resolve-agent-properties.mjs";
9
+ import { resolveAdcpVersion } from "../utils/adcp-version-config.mjs";
9
10
  import { AdAgentsRedirectRefusedError, ssrfSafeFetchAdAgents } from "./adagents-redirects.mjs";
10
11
  const MAX_ADAGENTS_BODY_BYTES = 256 * 1024;
11
12
  class PropertyCrawler {
12
13
  logger;
13
14
  userAgent;
15
+ adcpVersion;
16
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
17
+ servedVersions = /* @__PURE__ */ new Map();
14
18
  constructor(config) {
15
19
  this.logger = createLogger({
16
20
  level: config?.logLevel || "warn"
@@ -19,6 +23,9 @@ class PropertyCrawler {
19
23
  validateUserAgent(config.userAgent);
20
24
  }
21
25
  this.userAgent = config?.userAgent;
26
+ if (config?.adcpVersion !== void 0) {
27
+ this.adcpVersion = resolveAdcpVersion(config.adcpVersion);
28
+ }
22
29
  }
23
30
  /**
24
31
  * Crawl multiple agents to discover their publisher domains and properties
@@ -34,6 +41,7 @@ class PropertyCrawler {
34
41
  };
35
42
  const index = getPropertyIndex();
36
43
  const allPublisherDomains = /* @__PURE__ */ new Set();
44
+ this.servedVersions.clear();
37
45
  for (const agentInfo of agents) {
38
46
  try {
39
47
  const domains = await this.crawlAgent(agentInfo);
@@ -72,7 +80,9 @@ class PropertyCrawler {
72
80
  for (const agentUrl of claimingAgents) {
73
81
  let attributable;
74
82
  if (adAgentsFile) {
75
- const scope = resolveAgentProperties(adAgentsFile, agentUrl);
83
+ const scope = resolveAgentProperties(adAgentsFile, agentUrl, {
84
+ adcpVersion: this.servedVersions.get(agentUrl) ?? this.adcpVersion
85
+ });
76
86
  attributable = scope.properties;
77
87
  } else {
78
88
  attributable = properties;
@@ -97,10 +107,13 @@ class PropertyCrawler {
97
107
  protocol: agentInfo.protocol || "mcp",
98
108
  ...agentInfo.auth_token && { auth_token: agentInfo.auth_token }
99
109
  },
100
- { userAgent: this.userAgent }
110
+ { userAgent: this.userAgent, ...this.adcpVersion !== void 0 && { adcpVersion: this.adcpVersion } }
101
111
  );
102
112
  try {
103
113
  const capabilities = await client.getCapabilities();
114
+ if (capabilities.servedVersion) {
115
+ this.servedVersions.set(agentInfo.agent_url, capabilities.servedVersion);
116
+ }
104
117
  if (!capabilities.publisherDomains) {
105
118
  return [];
106
119
  }
@@ -25,6 +25,19 @@
25
25
  * top-level property to every listed agent is gone.
26
26
  */
27
27
  import type { AdAgentsJson, AuthorizedAgent, Property, PublisherPropertySelector, SinglePublisherPropertySelector } from './types.mjs';
28
+ /** Options shared by the `authorized_agents[].url` matching helpers. */
29
+ export interface AgentUrlMatchOptions {
30
+ /**
31
+ * AdCP release the caller negotiated or targets. Defaults to the SDK's
32
+ * pinned `ADCP_VERSION`.
33
+ *
34
+ * At 3.3 or later an origin-only entry (`https://agent.example.com`)
35
+ * authorizes the agent at that origin whatever its path. Below 3.3, or
36
+ * when the value is not a parseable AdCP version, every entry matches by
37
+ * exact canonical URL.
38
+ */
39
+ adcpVersion?: string;
40
+ }
28
41
  /**
29
42
  * Result of resolving a single agent's authorization scope against an
30
43
  * `adagents.json` file. `properties` are the locally-resolved entries
@@ -52,8 +65,39 @@ export interface ResolvedAgentScope {
52
65
  * iterate this array, not `cross_publisher` — see adcp#4504.
53
66
  */
54
67
  cross_publisher_expanded: SinglePublisherPropertySelector[];
55
- /** The matched agent entry, or `undefined` if no entry matched the agent URL. */
68
+ /**
69
+ * The matched agent entry, or `undefined` if no entry matched the agent URL.
70
+ * When several entries match (AdCP 3.3+), the first in document order; see
71
+ * {@link ResolvedAgentScope.matched_entries}.
72
+ */
56
73
  matched_entry?: AuthorizedAgent;
74
+ /**
75
+ * Every entry that matched the agent URL, in document order. At AdCP 3.3 or
76
+ * later more than one entry can match (an exact entry and an origin-only
77
+ * entry, say); the scope above is the union of theirs. Set at AdCP 3.3 or
78
+ * later whenever an entry matched; omitted below 3.3, where at most one
79
+ * entry can resolve.
80
+ *
81
+ * Per-entry fields the resolver does not combine are read from here.
82
+ * `signing_keys` combines by the rule in adcontextprotocol/adcp#9016, over
83
+ * the entries that match the agent AND authorize the signed message's scope
84
+ * (they resolve, are in their effective window, cover the country and the
85
+ * property). Use {@link resolvePublisherSigningKeyPin}, which takes that
86
+ * scope; this list alone is not scope-filtered.
87
+ *
88
+ * - **Pinned only if every such entry pins.** If any of them has no
89
+ * `signing_keys` (absent or empty), the publisher does not pin the agent
90
+ * for that message. An entry that authorizes nothing for the message
91
+ * never pins or unpins it.
92
+ * - **The allowed keys are the union.** When every such entry pins, the
93
+ * agent may sign with a key pinned by any of them.
94
+ * - **Per property.** A message about several properties must satisfy each
95
+ * property's pin, as it must satisfy each publisher's.
96
+ *
97
+ * The AAO directory's `signing_keys_pinned` is a scope-agnostic summary of
98
+ * the same rule.
99
+ */
100
+ matched_entries?: AuthorizedAgent[];
57
101
  /** Why the resolution returned an empty result, when it did. */
58
102
  unresolvable?: ResolveUnresolvableReason;
59
103
  }
@@ -88,18 +132,134 @@ export type ResolveUnresolvableReason =
88
132
  * resolver — e.g., TMP `seller_agent_url` validation.
89
133
  */
90
134
  export declare function canonicalizeAgentUrl(raw: string): string | null;
135
+ /**
136
+ * Whether `adcpVersion` (default: the SDK's pinned `ADCP_VERSION`) applies
137
+ * the 3.3 origin-only rule to `authorized_agents[].url` (adcp#8862).
138
+ */
139
+ export declare function usesOriginOnlyAgentMatching(adcpVersion?: string): boolean;
140
+ /**
141
+ * Whether `agentUrl` matches an `authorized_agents[].url` entry under
142
+ * [Agent URL matching](https://adcontextprotocol.org/docs/governance/property/adagents#agent-url-matching).
143
+ *
144
+ * Both sides are canonicalized with {@link canonicalizeAgentUrl}, so scheme
145
+ * and host case, default ports, unreserved percent-encoding and fragments
146
+ * never matter, and the scheme, host and port always do. A URL with userinfo
147
+ * never canonicalizes, so it matches nothing. Then:
148
+ *
149
+ * - **AdCP 3.3 or later** (DR-0023, adcp#8862): an origin-only entry, one
150
+ * whose canonical form has the root path and no query
151
+ * (`https://agent.example.com` or `https://agent.example.com/`),
152
+ * matches any agent URL with the same canonical origin, including
153
+ * `https://agent.example.com/mcp`. An entry with a path, or with a query
154
+ * (even an empty `?`), matches only the same canonical URL, so path case
155
+ * and a trailing slash (`/mcp` vs `/mcp/`) stay significant. Both sides
156
+ * also drop one trailing root-label dot from a DNS host
157
+ * (`https://agent.example.` matches `https://agent.example/mcp`), and a
158
+ * host ending in more than one dot matches nothing.
159
+ * - **AdCP 3.2 and earlier**: every entry matches only the same canonical
160
+ * URL, so an origin-only entry matches only an agent served at the root.
161
+ *
162
+ * Returns `false` when either URL fails to canonicalize.
163
+ */
164
+ export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUrl: string, options?: AgentUrlMatchOptions): boolean;
91
165
  /**
92
166
  * Resolve `agentUrl`'s authorization scope against an `adagents.json`
93
- * file. The lookup uses canonicalized URL comparison — two URLs
94
- * differing only in host case, default port, percent-encoding of
95
- * unreserved chars, or fragment are the same agent. Scheme and trailing
96
- * slash differences remain distinct.
167
+ * file. Entries are matched with {@link agentUrlMatchesAuthorizedEntry}:
168
+ * two URLs differing only in host case, default port, percent-encoding
169
+ * of unreserved chars, or fragment are the same agent, and scheme
170
+ * differences remain distinct. At AdCP 3.3 or later (`options.adcpVersion`,
171
+ * default the SDK's pinned `ADCP_VERSION`) an origin-only entry also
172
+ * matches an agent at any path on that origin; below 3.3 it matches only
173
+ * an agent served at the root. An entry with a path always matches only
174
+ * its canonical URL, trailing slash included.
175
+ *
176
+ * At 3.3 or later every matching entry authorizes the agent, and the scope
177
+ * is the union of theirs: `properties`, `cross_publisher` and
178
+ * `cross_publisher_expanded` combine (duplicates removed), so a narrower
179
+ * entry never removes scope another matching entry grants
180
+ * (adcontextprotocol/adcp#9011). `unresolvable` is set only when the union
181
+ * is empty, and then carries the first matching entry's reason.
182
+ *
183
+ * Below 3.3 the behaviour is unchanged: only exact canonical matches count,
184
+ * and more than one fails closed as `ambiguous_agent_url`.
97
185
  *
98
186
  * Returns `{ properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: '...' }`
99
187
  * (never throws) when the agent isn't listed, when its entry is
100
188
  * malformed, or when the agent uses a signals authorization type.
101
189
  */
102
- export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string): ResolvedAgentScope;
190
+ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string, options?: AgentUrlMatchOptions): ResolvedAgentScope;
191
+ /**
192
+ * The message a publisher pin is computed for (adcontextprotocol/adcp#9016).
193
+ * Pass the scope of the signed message: the pin comes only from entries that
194
+ * authorize it.
195
+ */
196
+ export interface PublisherSigningKeyPinOptions extends AgentUrlMatchOptions {
197
+ /**
198
+ * When the message applies, for `effective_from` / `effective_until`.
199
+ * Defaults to now. An entry outside its window authorizes nothing.
200
+ */
201
+ at?: Date | string | number;
202
+ /**
203
+ * ISO 3166-1 alpha-2 country the message concerns. An entry with
204
+ * `countries` authorizes the message only when this is one of them; with no
205
+ * country given, such an entry authorizes nothing.
206
+ */
207
+ country?: string;
208
+ /**
209
+ * The publisher's `property_id`s the message concerns. Each gets its own
210
+ * pin, and the result is the keys every one of them allows (a key must
211
+ * satisfy each property's pin). Omit to combine across every entry that
212
+ * authorizes the agent for anything.
213
+ */
214
+ propertyIds?: readonly string[];
215
+ }
216
+ /**
217
+ * The publisher's `signing_keys` pin for a message from `agentUrl`, read from
218
+ * the publisher's `adagents.json` (adcontextprotocol/adcp#9016). Use it as
219
+ * `PublisherSigningKeyPin.signingKeys`.
220
+ *
221
+ * Only entries that BOTH match `agentUrl` (with
222
+ * {@link agentUrlMatchesAuthorizedEntry}, so origin-only entries count at
223
+ * 3.3+) AND authorize the message's scope count. Such an entry:
224
+ * - resolves to something, so an unresolvable or signals-only entry does not count;
225
+ * - is inside its effective window at `at`;
226
+ * - covers `country`, and each property in `propertyIds`.
227
+ *
228
+ * An entry that authorizes nothing for the message never pins or unpins it,
229
+ * so callers MUST pass the message's scope.
230
+ *
231
+ * Among the entries that count:
232
+ * - The publisher pins the agent only if every one carries `signing_keys`. If
233
+ * any has none (absent or empty), the result is `undefined`: no pin, so use
234
+ * the agent's JWKS alone.
235
+ * - Otherwise the result is the union of their keys. Identical keys appear
236
+ * once. Copies that differ in `revoked_at` are all kept, so the earliest
237
+ * revocation applies whatever the entry order.
238
+ * - With `propertyIds`, each property gets its own pin, and the result keeps
239
+ * only the keys every pinned property allows.
240
+ *
241
+ * Returns `[]`, which `PublisherSigningKeyPin` reads as "accept no key", when
242
+ * the agent is NOT authorized for the message:
243
+ * - it is not listed;
244
+ * - below 3.3 it matches more than one exact entry (`ambiguous_agent_url`);
245
+ * - no entry authorizes the scope;
246
+ * - no entry authorizes one of `propertyIds`;
247
+ * - the pinned properties share no key.
248
+ *
249
+ * Not being authorized is never reported as "no pin".
250
+ *
251
+ * ```ts
252
+ * const pinFor = (adagents: AdAgentsJson) =>
253
+ * resolvePublisherSigningKeyPin(adagents, sellerAgentUrl, { adcpVersion, country, propertyIds });
254
+ * const pin: PublisherSigningKeyPin = {
255
+ * publisher: 'publisher.example',
256
+ * signingKeys: pinFor(adagents),
257
+ * // Your own uncached adagents.json fetch; null means the publisher no longer pins.
258
+ * refresh: async () => pinFor(await fetchAdagentsUncached()) ?? null,
259
+ * };
260
+ * ```
261
+ */
262
+ export declare function resolvePublisherSigningKeyPin(adAgents: AdAgentsJson, agentUrl: string, options?: PublisherSigningKeyPinOptions): Record<string, unknown>[] | undefined;
103
263
  /**
104
264
  * Convenience: list every locally-resolvable (`agent_url` →
105
265
  * `Property[]`) pair from an `adagents.json` file. Agents listed with
@@ -110,8 +270,10 @@ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl:
110
270
  *
111
271
  * The returned map is keyed by public canonical URL; if a file contains
112
272
  * canonical-equivalent entries, the later entry wins in this non-authoritative
113
- * inventory view. Use `resolveAgentProperties` for an authorization decision
114
- * for a specific agent URL because it fails closed on ambiguous matches.
273
+ * inventory view, and an origin-only entry is not applied to path-mounted
274
+ * agents. Use `resolveAgentProperties` for an authorization decision for a
275
+ * specific agent URL: it unions every matching entry at AdCP 3.3+ and fails
276
+ * closed on ambiguous matches below 3.3.
115
277
  */
116
278
  export declare function listAgentPropertyMap(adAgents: AdAgentsJson): {
117
279
  byAgent: Map<string, Property[]>;
@@ -25,6 +25,19 @@
25
25
  * top-level property to every listed agent is gone.
26
26
  */
27
27
  import type { AdAgentsJson, AuthorizedAgent, Property, PublisherPropertySelector, SinglePublisherPropertySelector } from './types';
28
+ /** Options shared by the `authorized_agents[].url` matching helpers. */
29
+ export interface AgentUrlMatchOptions {
30
+ /**
31
+ * AdCP release the caller negotiated or targets. Defaults to the SDK's
32
+ * pinned `ADCP_VERSION`.
33
+ *
34
+ * At 3.3 or later an origin-only entry (`https://agent.example.com`)
35
+ * authorizes the agent at that origin whatever its path. Below 3.3, or
36
+ * when the value is not a parseable AdCP version, every entry matches by
37
+ * exact canonical URL.
38
+ */
39
+ adcpVersion?: string;
40
+ }
28
41
  /**
29
42
  * Result of resolving a single agent's authorization scope against an
30
43
  * `adagents.json` file. `properties` are the locally-resolved entries
@@ -52,8 +65,39 @@ export interface ResolvedAgentScope {
52
65
  * iterate this array, not `cross_publisher` — see adcp#4504.
53
66
  */
54
67
  cross_publisher_expanded: SinglePublisherPropertySelector[];
55
- /** The matched agent entry, or `undefined` if no entry matched the agent URL. */
68
+ /**
69
+ * The matched agent entry, or `undefined` if no entry matched the agent URL.
70
+ * When several entries match (AdCP 3.3+), the first in document order; see
71
+ * {@link ResolvedAgentScope.matched_entries}.
72
+ */
56
73
  matched_entry?: AuthorizedAgent;
74
+ /**
75
+ * Every entry that matched the agent URL, in document order. At AdCP 3.3 or
76
+ * later more than one entry can match (an exact entry and an origin-only
77
+ * entry, say); the scope above is the union of theirs. Set at AdCP 3.3 or
78
+ * later whenever an entry matched; omitted below 3.3, where at most one
79
+ * entry can resolve.
80
+ *
81
+ * Per-entry fields the resolver does not combine are read from here.
82
+ * `signing_keys` combines by the rule in adcontextprotocol/adcp#9016, over
83
+ * the entries that match the agent AND authorize the signed message's scope
84
+ * (they resolve, are in their effective window, cover the country and the
85
+ * property). Use {@link resolvePublisherSigningKeyPin}, which takes that
86
+ * scope; this list alone is not scope-filtered.
87
+ *
88
+ * - **Pinned only if every such entry pins.** If any of them has no
89
+ * `signing_keys` (absent or empty), the publisher does not pin the agent
90
+ * for that message. An entry that authorizes nothing for the message
91
+ * never pins or unpins it.
92
+ * - **The allowed keys are the union.** When every such entry pins, the
93
+ * agent may sign with a key pinned by any of them.
94
+ * - **Per property.** A message about several properties must satisfy each
95
+ * property's pin, as it must satisfy each publisher's.
96
+ *
97
+ * The AAO directory's `signing_keys_pinned` is a scope-agnostic summary of
98
+ * the same rule.
99
+ */
100
+ matched_entries?: AuthorizedAgent[];
57
101
  /** Why the resolution returned an empty result, when it did. */
58
102
  unresolvable?: ResolveUnresolvableReason;
59
103
  }
@@ -88,18 +132,134 @@ export type ResolveUnresolvableReason =
88
132
  * resolver — e.g., TMP `seller_agent_url` validation.
89
133
  */
90
134
  export declare function canonicalizeAgentUrl(raw: string): string | null;
135
+ /**
136
+ * Whether `adcpVersion` (default: the SDK's pinned `ADCP_VERSION`) applies
137
+ * the 3.3 origin-only rule to `authorized_agents[].url` (adcp#8862).
138
+ */
139
+ export declare function usesOriginOnlyAgentMatching(adcpVersion?: string): boolean;
140
+ /**
141
+ * Whether `agentUrl` matches an `authorized_agents[].url` entry under
142
+ * [Agent URL matching](https://adcontextprotocol.org/docs/governance/property/adagents#agent-url-matching).
143
+ *
144
+ * Both sides are canonicalized with {@link canonicalizeAgentUrl}, so scheme
145
+ * and host case, default ports, unreserved percent-encoding and fragments
146
+ * never matter, and the scheme, host and port always do. A URL with userinfo
147
+ * never canonicalizes, so it matches nothing. Then:
148
+ *
149
+ * - **AdCP 3.3 or later** (DR-0023, adcp#8862): an origin-only entry, one
150
+ * whose canonical form has the root path and no query
151
+ * (`https://agent.example.com` or `https://agent.example.com/`),
152
+ * matches any agent URL with the same canonical origin, including
153
+ * `https://agent.example.com/mcp`. An entry with a path, or with a query
154
+ * (even an empty `?`), matches only the same canonical URL, so path case
155
+ * and a trailing slash (`/mcp` vs `/mcp/`) stay significant. Both sides
156
+ * also drop one trailing root-label dot from a DNS host
157
+ * (`https://agent.example.` matches `https://agent.example/mcp`), and a
158
+ * host ending in more than one dot matches nothing.
159
+ * - **AdCP 3.2 and earlier**: every entry matches only the same canonical
160
+ * URL, so an origin-only entry matches only an agent served at the root.
161
+ *
162
+ * Returns `false` when either URL fails to canonicalize.
163
+ */
164
+ export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUrl: string, options?: AgentUrlMatchOptions): boolean;
91
165
  /**
92
166
  * Resolve `agentUrl`'s authorization scope against an `adagents.json`
93
- * file. The lookup uses canonicalized URL comparison — two URLs
94
- * differing only in host case, default port, percent-encoding of
95
- * unreserved chars, or fragment are the same agent. Scheme and trailing
96
- * slash differences remain distinct.
167
+ * file. Entries are matched with {@link agentUrlMatchesAuthorizedEntry}:
168
+ * two URLs differing only in host case, default port, percent-encoding
169
+ * of unreserved chars, or fragment are the same agent, and scheme
170
+ * differences remain distinct. At AdCP 3.3 or later (`options.adcpVersion`,
171
+ * default the SDK's pinned `ADCP_VERSION`) an origin-only entry also
172
+ * matches an agent at any path on that origin; below 3.3 it matches only
173
+ * an agent served at the root. An entry with a path always matches only
174
+ * its canonical URL, trailing slash included.
175
+ *
176
+ * At 3.3 or later every matching entry authorizes the agent, and the scope
177
+ * is the union of theirs: `properties`, `cross_publisher` and
178
+ * `cross_publisher_expanded` combine (duplicates removed), so a narrower
179
+ * entry never removes scope another matching entry grants
180
+ * (adcontextprotocol/adcp#9011). `unresolvable` is set only when the union
181
+ * is empty, and then carries the first matching entry's reason.
182
+ *
183
+ * Below 3.3 the behaviour is unchanged: only exact canonical matches count,
184
+ * and more than one fails closed as `ambiguous_agent_url`.
97
185
  *
98
186
  * Returns `{ properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: '...' }`
99
187
  * (never throws) when the agent isn't listed, when its entry is
100
188
  * malformed, or when the agent uses a signals authorization type.
101
189
  */
102
- export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string): ResolvedAgentScope;
190
+ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string, options?: AgentUrlMatchOptions): ResolvedAgentScope;
191
+ /**
192
+ * The message a publisher pin is computed for (adcontextprotocol/adcp#9016).
193
+ * Pass the scope of the signed message: the pin comes only from entries that
194
+ * authorize it.
195
+ */
196
+ export interface PublisherSigningKeyPinOptions extends AgentUrlMatchOptions {
197
+ /**
198
+ * When the message applies, for `effective_from` / `effective_until`.
199
+ * Defaults to now. An entry outside its window authorizes nothing.
200
+ */
201
+ at?: Date | string | number;
202
+ /**
203
+ * ISO 3166-1 alpha-2 country the message concerns. An entry with
204
+ * `countries` authorizes the message only when this is one of them; with no
205
+ * country given, such an entry authorizes nothing.
206
+ */
207
+ country?: string;
208
+ /**
209
+ * The publisher's `property_id`s the message concerns. Each gets its own
210
+ * pin, and the result is the keys every one of them allows (a key must
211
+ * satisfy each property's pin). Omit to combine across every entry that
212
+ * authorizes the agent for anything.
213
+ */
214
+ propertyIds?: readonly string[];
215
+ }
216
+ /**
217
+ * The publisher's `signing_keys` pin for a message from `agentUrl`, read from
218
+ * the publisher's `adagents.json` (adcontextprotocol/adcp#9016). Use it as
219
+ * `PublisherSigningKeyPin.signingKeys`.
220
+ *
221
+ * Only entries that BOTH match `agentUrl` (with
222
+ * {@link agentUrlMatchesAuthorizedEntry}, so origin-only entries count at
223
+ * 3.3+) AND authorize the message's scope count. Such an entry:
224
+ * - resolves to something, so an unresolvable or signals-only entry does not count;
225
+ * - is inside its effective window at `at`;
226
+ * - covers `country`, and each property in `propertyIds`.
227
+ *
228
+ * An entry that authorizes nothing for the message never pins or unpins it,
229
+ * so callers MUST pass the message's scope.
230
+ *
231
+ * Among the entries that count:
232
+ * - The publisher pins the agent only if every one carries `signing_keys`. If
233
+ * any has none (absent or empty), the result is `undefined`: no pin, so use
234
+ * the agent's JWKS alone.
235
+ * - Otherwise the result is the union of their keys. Identical keys appear
236
+ * once. Copies that differ in `revoked_at` are all kept, so the earliest
237
+ * revocation applies whatever the entry order.
238
+ * - With `propertyIds`, each property gets its own pin, and the result keeps
239
+ * only the keys every pinned property allows.
240
+ *
241
+ * Returns `[]`, which `PublisherSigningKeyPin` reads as "accept no key", when
242
+ * the agent is NOT authorized for the message:
243
+ * - it is not listed;
244
+ * - below 3.3 it matches more than one exact entry (`ambiguous_agent_url`);
245
+ * - no entry authorizes the scope;
246
+ * - no entry authorizes one of `propertyIds`;
247
+ * - the pinned properties share no key.
248
+ *
249
+ * Not being authorized is never reported as "no pin".
250
+ *
251
+ * ```ts
252
+ * const pinFor = (adagents: AdAgentsJson) =>
253
+ * resolvePublisherSigningKeyPin(adagents, sellerAgentUrl, { adcpVersion, country, propertyIds });
254
+ * const pin: PublisherSigningKeyPin = {
255
+ * publisher: 'publisher.example',
256
+ * signingKeys: pinFor(adagents),
257
+ * // Your own uncached adagents.json fetch; null means the publisher no longer pins.
258
+ * refresh: async () => pinFor(await fetchAdagentsUncached()) ?? null,
259
+ * };
260
+ * ```
261
+ */
262
+ export declare function resolvePublisherSigningKeyPin(adAgents: AdAgentsJson, agentUrl: string, options?: PublisherSigningKeyPinOptions): Record<string, unknown>[] | undefined;
103
263
  /**
104
264
  * Convenience: list every locally-resolvable (`agent_url` →
105
265
  * `Property[]`) pair from an `adagents.json` file. Agents listed with
@@ -110,8 +270,10 @@ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl:
110
270
  *
111
271
  * The returned map is keyed by public canonical URL; if a file contains
112
272
  * canonical-equivalent entries, the later entry wins in this non-authoritative
113
- * inventory view. Use `resolveAgentProperties` for an authorization decision
114
- * for a specific agent URL because it fails closed on ambiguous matches.
273
+ * inventory view, and an origin-only entry is not applied to path-mounted
274
+ * agents. Use `resolveAgentProperties` for an authorization decision for a
275
+ * specific agent URL: it unions every matching entry at AdCP 3.3+ and fails
276
+ * closed on ambiguous matches below 3.3.
115
277
  */
116
278
  export declare function listAgentPropertyMap(adAgents: AdAgentsJson): {
117
279
  byAgent: Map<string, Property[]>;