@adcp/sdk 17.0.0-beta.25 → 17.0.0-beta.26
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.
- package/dist/lib/discovery/property-crawler.d.mts +11 -0
- package/dist/lib/discovery/property-crawler.d.ts +11 -0
- package/dist/lib/discovery/property-crawler.js +15 -2
- package/dist/lib/discovery/property-crawler.mjs +15 -2
- package/dist/lib/discovery/resolve-agent-properties.d.mts +81 -8
- package/dist/lib/discovery/resolve-agent-properties.d.ts +81 -8
- package/dist/lib/discovery/resolve-agent-properties.js +94 -14
- package/dist/lib/discovery/resolve-agent-properties.mjs +91 -13
- package/dist/lib/discovery/validate-adagents.d.mts +7 -0
- package/dist/lib/discovery/validate-adagents.d.ts +7 -0
- package/dist/lib/entrypoints/discovery.d.mts +1 -1
- package/dist/lib/entrypoints/discovery.d.ts +1 -1
- package/dist/lib/entrypoints/discovery.js +4 -0
- package/dist/lib/entrypoints/discovery.mjs +5 -1
- package/dist/lib/index.d.mts +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/index.js +4 -0
- package/dist/lib/index.mjs +5 -1
- package/dist/lib/supply-path/validation.d.mts +8 -0
- package/dist/lib/supply-path/validation.d.ts +8 -0
- package/dist/lib/testing/compliance/comply.js +1 -1
- package/dist/lib/testing/compliance/comply.mjs +3 -2
- package/dist/lib/testing/storyboard/index.d.mts +1 -1
- package/dist/lib/testing/storyboard/index.d.ts +1 -1
- package/dist/lib/testing/storyboard/index.js +6 -0
- package/dist/lib/testing/storyboard/index.mjs +6 -0
- package/dist/lib/testing/storyboard/loader.js +52 -28
- package/dist/lib/testing/storyboard/loader.mjs +52 -28
- package/dist/lib/testing/storyboard/runner.d.mts +24 -1
- package/dist/lib/testing/storyboard/runner.d.ts +24 -1
- package/dist/lib/testing/storyboard/runner.js +75 -7
- package/dist/lib/testing/storyboard/runner.mjs +72 -7
- package/dist/lib/testing/storyboard/types.d.mts +51 -6
- package/dist/lib/testing/storyboard/types.d.ts +51 -6
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
- package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
- package/dist/lib/version.d.mts +3 -3
- package/dist/lib/version.d.ts +3 -3
- package/dist/lib/version.js +3 -3
- package/dist/lib/version.mjs +3 -3
- package/docs/TYPE-SUMMARY.md +1 -1
- package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
- package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
- package/docs/llms.txt +1 -1
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-16-to-17.md +25 -0
- package/package.json +1 -1
|
@@ -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,22 @@ export interface ResolvedAgentScope {
|
|
|
52
65
|
* iterate this array, not `cross_publisher` — see adcp#4504.
|
|
53
66
|
*/
|
|
54
67
|
cross_publisher_expanded: SinglePublisherPropertySelector[];
|
|
55
|
-
/**
|
|
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. Per-entry fields the
|
|
78
|
+
* resolver does not combine, such as `signing_keys`, are read from here: the
|
|
79
|
+
* AAO registry reports keys as pinned when any matching entry pins one
|
|
80
|
+
* (adcontextprotocol/adcp#9011). Set at AdCP 3.3 or later whenever an
|
|
81
|
+
* entry matched; omitted below 3.3, where at most one entry can resolve.
|
|
82
|
+
*/
|
|
83
|
+
matched_entries?: AuthorizedAgent[];
|
|
57
84
|
/** Why the resolution returned an empty result, when it did. */
|
|
58
85
|
unresolvable?: ResolveUnresolvableReason;
|
|
59
86
|
}
|
|
@@ -88,18 +115,62 @@ export type ResolveUnresolvableReason =
|
|
|
88
115
|
* resolver — e.g., TMP `seller_agent_url` validation.
|
|
89
116
|
*/
|
|
90
117
|
export declare function canonicalizeAgentUrl(raw: string): string | null;
|
|
118
|
+
/**
|
|
119
|
+
* Whether `adcpVersion` (default: the SDK's pinned `ADCP_VERSION`) applies
|
|
120
|
+
* the 3.3 origin-only rule to `authorized_agents[].url` (adcp#8862).
|
|
121
|
+
*/
|
|
122
|
+
export declare function usesOriginOnlyAgentMatching(adcpVersion?: string): boolean;
|
|
123
|
+
/**
|
|
124
|
+
* Whether `agentUrl` matches an `authorized_agents[].url` entry under
|
|
125
|
+
* [Agent URL matching](https://adcontextprotocol.org/docs/governance/property/adagents#agent-url-matching).
|
|
126
|
+
*
|
|
127
|
+
* Both sides are canonicalized with {@link canonicalizeAgentUrl}, so scheme
|
|
128
|
+
* and host case, default ports, unreserved percent-encoding and fragments
|
|
129
|
+
* never matter, and the scheme, host and port always do. A URL with userinfo
|
|
130
|
+
* never canonicalizes, so it matches nothing. Then:
|
|
131
|
+
*
|
|
132
|
+
* - **AdCP 3.3 or later** (DR-0023, adcp#8862): an origin-only entry, one
|
|
133
|
+
* whose canonical form has the root path and no query
|
|
134
|
+
* (`https://agent.example.com` or `https://agent.example.com/`),
|
|
135
|
+
* matches any agent URL with the same canonical origin, including
|
|
136
|
+
* `https://agent.example.com/mcp`. An entry with a path, or with a query
|
|
137
|
+
* (even an empty `?`), matches only the same canonical URL, so path case
|
|
138
|
+
* and a trailing slash (`/mcp` vs `/mcp/`) stay significant. Both sides
|
|
139
|
+
* also drop one trailing root-label dot from a DNS host
|
|
140
|
+
* (`https://agent.example.` matches `https://agent.example/mcp`), and a
|
|
141
|
+
* host ending in more than one dot matches nothing.
|
|
142
|
+
* - **AdCP 3.2 and earlier**: every entry matches only the same canonical
|
|
143
|
+
* URL, so an origin-only entry matches only an agent served at the root.
|
|
144
|
+
*
|
|
145
|
+
* Returns `false` when either URL fails to canonicalize.
|
|
146
|
+
*/
|
|
147
|
+
export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUrl: string, options?: AgentUrlMatchOptions): boolean;
|
|
91
148
|
/**
|
|
92
149
|
* Resolve `agentUrl`'s authorization scope against an `adagents.json`
|
|
93
|
-
* file.
|
|
94
|
-
* differing only in host case, default port, percent-encoding
|
|
95
|
-
* unreserved chars, or fragment are the same agent
|
|
96
|
-
*
|
|
150
|
+
* file. Entries are matched with {@link agentUrlMatchesAuthorizedEntry}:
|
|
151
|
+
* two URLs differing only in host case, default port, percent-encoding
|
|
152
|
+
* of unreserved chars, or fragment are the same agent, and scheme
|
|
153
|
+
* differences remain distinct. At AdCP 3.3 or later (`options.adcpVersion`,
|
|
154
|
+
* default the SDK's pinned `ADCP_VERSION`) an origin-only entry also
|
|
155
|
+
* matches an agent at any path on that origin; below 3.3 it matches only
|
|
156
|
+
* an agent served at the root. An entry with a path always matches only
|
|
157
|
+
* its canonical URL, trailing slash included.
|
|
158
|
+
*
|
|
159
|
+
* At 3.3 or later every matching entry authorizes the agent, and the scope
|
|
160
|
+
* is the union of theirs: `properties`, `cross_publisher` and
|
|
161
|
+
* `cross_publisher_expanded` combine (duplicates removed), so a narrower
|
|
162
|
+
* entry never removes scope another matching entry grants
|
|
163
|
+
* (adcontextprotocol/adcp#9011). `unresolvable` is set only when the union
|
|
164
|
+
* is empty, and then carries the first matching entry's reason.
|
|
165
|
+
*
|
|
166
|
+
* Below 3.3 the behaviour is unchanged: only exact canonical matches count,
|
|
167
|
+
* and more than one fails closed as `ambiguous_agent_url`.
|
|
97
168
|
*
|
|
98
169
|
* Returns `{ properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: '...' }`
|
|
99
170
|
* (never throws) when the agent isn't listed, when its entry is
|
|
100
171
|
* malformed, or when the agent uses a signals authorization type.
|
|
101
172
|
*/
|
|
102
|
-
export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string): ResolvedAgentScope;
|
|
173
|
+
export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string, options?: AgentUrlMatchOptions): ResolvedAgentScope;
|
|
103
174
|
/**
|
|
104
175
|
* Convenience: list every locally-resolvable (`agent_url` →
|
|
105
176
|
* `Property[]`) pair from an `adagents.json` file. Agents listed with
|
|
@@ -110,8 +181,10 @@ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl:
|
|
|
110
181
|
*
|
|
111
182
|
* The returned map is keyed by public canonical URL; if a file contains
|
|
112
183
|
* canonical-equivalent entries, the later entry wins in this non-authoritative
|
|
113
|
-
* inventory view
|
|
114
|
-
*
|
|
184
|
+
* inventory view, and an origin-only entry is not applied to path-mounted
|
|
185
|
+
* agents. Use `resolveAgentProperties` for an authorization decision for a
|
|
186
|
+
* specific agent URL: it unions every matching entry at AdCP 3.3+ and fails
|
|
187
|
+
* closed on ambiguous matches below 3.3.
|
|
115
188
|
*/
|
|
116
189
|
export declare function listAgentPropertyMap(adAgents: AdAgentsJson): {
|
|
117
190
|
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,22 @@ export interface ResolvedAgentScope {
|
|
|
52
65
|
* iterate this array, not `cross_publisher` — see adcp#4504.
|
|
53
66
|
*/
|
|
54
67
|
cross_publisher_expanded: SinglePublisherPropertySelector[];
|
|
55
|
-
/**
|
|
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. Per-entry fields the
|
|
78
|
+
* resolver does not combine, such as `signing_keys`, are read from here: the
|
|
79
|
+
* AAO registry reports keys as pinned when any matching entry pins one
|
|
80
|
+
* (adcontextprotocol/adcp#9011). Set at AdCP 3.3 or later whenever an
|
|
81
|
+
* entry matched; omitted below 3.3, where at most one entry can resolve.
|
|
82
|
+
*/
|
|
83
|
+
matched_entries?: AuthorizedAgent[];
|
|
57
84
|
/** Why the resolution returned an empty result, when it did. */
|
|
58
85
|
unresolvable?: ResolveUnresolvableReason;
|
|
59
86
|
}
|
|
@@ -88,18 +115,62 @@ export type ResolveUnresolvableReason =
|
|
|
88
115
|
* resolver — e.g., TMP `seller_agent_url` validation.
|
|
89
116
|
*/
|
|
90
117
|
export declare function canonicalizeAgentUrl(raw: string): string | null;
|
|
118
|
+
/**
|
|
119
|
+
* Whether `adcpVersion` (default: the SDK's pinned `ADCP_VERSION`) applies
|
|
120
|
+
* the 3.3 origin-only rule to `authorized_agents[].url` (adcp#8862).
|
|
121
|
+
*/
|
|
122
|
+
export declare function usesOriginOnlyAgentMatching(adcpVersion?: string): boolean;
|
|
123
|
+
/**
|
|
124
|
+
* Whether `agentUrl` matches an `authorized_agents[].url` entry under
|
|
125
|
+
* [Agent URL matching](https://adcontextprotocol.org/docs/governance/property/adagents#agent-url-matching).
|
|
126
|
+
*
|
|
127
|
+
* Both sides are canonicalized with {@link canonicalizeAgentUrl}, so scheme
|
|
128
|
+
* and host case, default ports, unreserved percent-encoding and fragments
|
|
129
|
+
* never matter, and the scheme, host and port always do. A URL with userinfo
|
|
130
|
+
* never canonicalizes, so it matches nothing. Then:
|
|
131
|
+
*
|
|
132
|
+
* - **AdCP 3.3 or later** (DR-0023, adcp#8862): an origin-only entry, one
|
|
133
|
+
* whose canonical form has the root path and no query
|
|
134
|
+
* (`https://agent.example.com` or `https://agent.example.com/`),
|
|
135
|
+
* matches any agent URL with the same canonical origin, including
|
|
136
|
+
* `https://agent.example.com/mcp`. An entry with a path, or with a query
|
|
137
|
+
* (even an empty `?`), matches only the same canonical URL, so path case
|
|
138
|
+
* and a trailing slash (`/mcp` vs `/mcp/`) stay significant. Both sides
|
|
139
|
+
* also drop one trailing root-label dot from a DNS host
|
|
140
|
+
* (`https://agent.example.` matches `https://agent.example/mcp`), and a
|
|
141
|
+
* host ending in more than one dot matches nothing.
|
|
142
|
+
* - **AdCP 3.2 and earlier**: every entry matches only the same canonical
|
|
143
|
+
* URL, so an origin-only entry matches only an agent served at the root.
|
|
144
|
+
*
|
|
145
|
+
* Returns `false` when either URL fails to canonicalize.
|
|
146
|
+
*/
|
|
147
|
+
export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUrl: string, options?: AgentUrlMatchOptions): boolean;
|
|
91
148
|
/**
|
|
92
149
|
* Resolve `agentUrl`'s authorization scope against an `adagents.json`
|
|
93
|
-
* file.
|
|
94
|
-
* differing only in host case, default port, percent-encoding
|
|
95
|
-
* unreserved chars, or fragment are the same agent
|
|
96
|
-
*
|
|
150
|
+
* file. Entries are matched with {@link agentUrlMatchesAuthorizedEntry}:
|
|
151
|
+
* two URLs differing only in host case, default port, percent-encoding
|
|
152
|
+
* of unreserved chars, or fragment are the same agent, and scheme
|
|
153
|
+
* differences remain distinct. At AdCP 3.3 or later (`options.adcpVersion`,
|
|
154
|
+
* default the SDK's pinned `ADCP_VERSION`) an origin-only entry also
|
|
155
|
+
* matches an agent at any path on that origin; below 3.3 it matches only
|
|
156
|
+
* an agent served at the root. An entry with a path always matches only
|
|
157
|
+
* its canonical URL, trailing slash included.
|
|
158
|
+
*
|
|
159
|
+
* At 3.3 or later every matching entry authorizes the agent, and the scope
|
|
160
|
+
* is the union of theirs: `properties`, `cross_publisher` and
|
|
161
|
+
* `cross_publisher_expanded` combine (duplicates removed), so a narrower
|
|
162
|
+
* entry never removes scope another matching entry grants
|
|
163
|
+
* (adcontextprotocol/adcp#9011). `unresolvable` is set only when the union
|
|
164
|
+
* is empty, and then carries the first matching entry's reason.
|
|
165
|
+
*
|
|
166
|
+
* Below 3.3 the behaviour is unchanged: only exact canonical matches count,
|
|
167
|
+
* and more than one fails closed as `ambiguous_agent_url`.
|
|
97
168
|
*
|
|
98
169
|
* Returns `{ properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: '...' }`
|
|
99
170
|
* (never throws) when the agent isn't listed, when its entry is
|
|
100
171
|
* malformed, or when the agent uses a signals authorization type.
|
|
101
172
|
*/
|
|
102
|
-
export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string): ResolvedAgentScope;
|
|
173
|
+
export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string, options?: AgentUrlMatchOptions): ResolvedAgentScope;
|
|
103
174
|
/**
|
|
104
175
|
* Convenience: list every locally-resolvable (`agent_url` →
|
|
105
176
|
* `Property[]`) pair from an `adagents.json` file. Agents listed with
|
|
@@ -110,8 +181,10 @@ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl:
|
|
|
110
181
|
*
|
|
111
182
|
* The returned map is keyed by public canonical URL; if a file contains
|
|
112
183
|
* canonical-equivalent entries, the later entry wins in this non-authoritative
|
|
113
|
-
* inventory view
|
|
114
|
-
*
|
|
184
|
+
* inventory view, and an origin-only entry is not applied to path-mounted
|
|
185
|
+
* agents. Use `resolveAgentProperties` for an authorization decision for a
|
|
186
|
+
* specific agent URL: it unions every matching entry at AdCP 3.3+ and fails
|
|
187
|
+
* closed on ambiguous matches below 3.3.
|
|
115
188
|
*/
|
|
116
189
|
export declare function listAgentPropertyMap(adAgents: AdAgentsJson): {
|
|
117
190
|
byAgent: Map<string, Property[]>;
|
|
@@ -18,13 +18,18 @@ var __copyProps = (to, from, except, desc) => {
|
|
|
18
18
|
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
19
|
var resolve_agent_properties_exports = {};
|
|
20
20
|
__export(resolve_agent_properties_exports, {
|
|
21
|
+
agentUrlMatchesAuthorizedEntry: () => agentUrlMatchesAuthorizedEntry,
|
|
21
22
|
canonicalizeAgentUrl: () => canonicalizeAgentUrl,
|
|
22
23
|
getAllProperties: () => getAllProperties,
|
|
23
24
|
listAgentPropertyMap: () => listAgentPropertyMap,
|
|
24
|
-
resolveAgentProperties: () => resolveAgentProperties
|
|
25
|
+
resolveAgentProperties: () => resolveAgentProperties,
|
|
26
|
+
usesOriginOnlyAgentMatching: () => usesOriginOnlyAgentMatching
|
|
25
27
|
});
|
|
26
28
|
module.exports = __toCommonJS(resolve_agent_properties_exports);
|
|
27
29
|
var import_inline_publisher_properties = require('./inline-publisher-properties.js');
|
|
30
|
+
var import_version = require('../version.js');
|
|
31
|
+
var import_adcp_version_config = require('../utils/adcp-version-config.js');
|
|
32
|
+
const ORIGIN_ONLY_AGENT_MATCHING_SINCE = "3.3.0-beta.0";
|
|
28
33
|
function canonicalizeAgentUrl(raw) {
|
|
29
34
|
const parsed = parseAgentUrl(raw);
|
|
30
35
|
if (!parsed) return null;
|
|
@@ -33,6 +38,38 @@ function canonicalizeAgentUrl(raw) {
|
|
|
33
38
|
const query = parsed.search ? decodeUnreservedPercentEncoding(parsed.search) : fragmentlessHref.endsWith("?") ? "?" : "";
|
|
34
39
|
return `${parsed.protocol}//${parsed.host}${path}${query}`;
|
|
35
40
|
}
|
|
41
|
+
function canonicalAgentUrlParts(raw) {
|
|
42
|
+
const url = canonicalizeAgentUrl(raw);
|
|
43
|
+
if (url === null) return null;
|
|
44
|
+
const parsed = new URL(url);
|
|
45
|
+
const origin = `${parsed.protocol}//${parsed.host}`;
|
|
46
|
+
return { url, originOnly: url === `${origin}/`, rootDotless: stripRootDot(parsed, url, origin) };
|
|
47
|
+
}
|
|
48
|
+
function stripRootDot(parsed, url, origin) {
|
|
49
|
+
const host = parsed.hostname;
|
|
50
|
+
if (host.startsWith("[") || !host.endsWith(".")) return { url, origin };
|
|
51
|
+
if (host.endsWith("..") || host === ".") return null;
|
|
52
|
+
const dotless = `${parsed.protocol}//${host.slice(0, -1)}${parsed.port ? `:${parsed.port}` : ""}`;
|
|
53
|
+
return { url: dotless + url.slice(origin.length), origin: dotless };
|
|
54
|
+
}
|
|
55
|
+
function usesOriginOnlyAgentMatching(adcpVersion = import_version.ADCP_VERSION) {
|
|
56
|
+
return (0, import_adcp_version_config.isAdcpVersionAtLeast)(adcpVersion, ORIGIN_ONLY_AGENT_MATCHING_SINCE);
|
|
57
|
+
}
|
|
58
|
+
function agentUrlMatchesAuthorizedEntry(entryUrl, agentUrl, options = {}) {
|
|
59
|
+
const entry = canonicalAgentUrlParts(entryUrl);
|
|
60
|
+
const agent = canonicalAgentUrlParts(agentUrl);
|
|
61
|
+
if (!entry || !agent) return false;
|
|
62
|
+
return matchCanonicalAgentUrl(entry, agent, usesOriginOnlyAgentMatching(options.adcpVersion)) !== "none";
|
|
63
|
+
}
|
|
64
|
+
function matchCanonicalAgentUrl(entry, agent, originOnlyMatching) {
|
|
65
|
+
if (!originOnlyMatching) return entry.url === agent.url ? "exact" : "none";
|
|
66
|
+
const e = entry.rootDotless;
|
|
67
|
+
const a = agent.rootDotless;
|
|
68
|
+
if (!e || !a) return "none";
|
|
69
|
+
if (e.url === a.url) return "exact";
|
|
70
|
+
if (entry.originOnly && e.origin === a.origin) return "origin";
|
|
71
|
+
return "none";
|
|
72
|
+
}
|
|
36
73
|
function parseAgentUrl(raw) {
|
|
37
74
|
if (typeof raw !== "string" || raw.length === 0) return null;
|
|
38
75
|
let parsed;
|
|
@@ -45,25 +82,66 @@ function parseAgentUrl(raw) {
|
|
|
45
82
|
if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
|
|
46
83
|
return parsed;
|
|
47
84
|
}
|
|
48
|
-
function resolveAgentProperties(adAgents, agentUrl) {
|
|
49
|
-
const wanted =
|
|
85
|
+
function resolveAgentProperties(adAgents, agentUrl, options = {}) {
|
|
86
|
+
const wanted = canonicalAgentUrlParts(agentUrl);
|
|
50
87
|
if (!wanted) {
|
|
51
88
|
return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
|
|
52
89
|
}
|
|
90
|
+
const originOnlyMatching = usesOriginOnlyAgentMatching(options.adcpVersion);
|
|
53
91
|
const entries = Array.isArray(adAgents.authorized_agents) ? adAgents.authorized_agents : [];
|
|
54
|
-
const matches =
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
|
|
92
|
+
const matches = [];
|
|
93
|
+
for (const e of entries) {
|
|
94
|
+
if (!e || typeof e.url !== "string") continue;
|
|
95
|
+
const canon = canonicalAgentUrlParts(e.url);
|
|
96
|
+
if (!canon) continue;
|
|
97
|
+
if (matchCanonicalAgentUrl(canon, wanted, originOnlyMatching) !== "none") matches.push(e);
|
|
61
98
|
}
|
|
62
|
-
const
|
|
63
|
-
if (!
|
|
99
|
+
const first = matches[0];
|
|
100
|
+
if (!first) {
|
|
64
101
|
return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
|
|
65
102
|
}
|
|
66
|
-
|
|
103
|
+
if (!originOnlyMatching) {
|
|
104
|
+
if (matches.length > 1) {
|
|
105
|
+
return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
|
|
106
|
+
}
|
|
107
|
+
return resolveMatchedAgentProperties(adAgents, first);
|
|
108
|
+
}
|
|
109
|
+
if (matches.length === 1) {
|
|
110
|
+
return { ...resolveMatchedAgentProperties(adAgents, first), matched_entries: [first] };
|
|
111
|
+
}
|
|
112
|
+
return unionAgentScopes(
|
|
113
|
+
matches.map((entry) => resolveMatchedAgentProperties(adAgents, entry)),
|
|
114
|
+
matches
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
function unionAgentScopes(scopes, entries) {
|
|
118
|
+
const properties = uniqueByValue(scopes.flatMap((s) => s.properties));
|
|
119
|
+
const cross_publisher = uniqueByValue(scopes.flatMap((s) => s.cross_publisher));
|
|
120
|
+
const cross_publisher_expanded = uniqueByValue(scopes.flatMap((s) => s.cross_publisher_expanded));
|
|
121
|
+
const empty = properties.length === 0 && cross_publisher.length === 0;
|
|
122
|
+
const reason = scopes.find((s) => s.unresolvable !== void 0)?.unresolvable;
|
|
123
|
+
return {
|
|
124
|
+
properties,
|
|
125
|
+
cross_publisher,
|
|
126
|
+
cross_publisher_expanded,
|
|
127
|
+
matched_entry: entries[0],
|
|
128
|
+
matched_entries: entries,
|
|
129
|
+
...empty && reason !== void 0 ? { unresolvable: reason } : {}
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
function uniqueByValue(items) {
|
|
133
|
+
const seenRefs = /* @__PURE__ */ new Set();
|
|
134
|
+
const seenValues = /* @__PURE__ */ new Set();
|
|
135
|
+
const out = [];
|
|
136
|
+
for (const item of items) {
|
|
137
|
+
if (seenRefs.has(item)) continue;
|
|
138
|
+
seenRefs.add(item);
|
|
139
|
+
const value = JSON.stringify(item);
|
|
140
|
+
if (seenValues.has(value)) continue;
|
|
141
|
+
seenValues.add(value);
|
|
142
|
+
out.push(item);
|
|
143
|
+
}
|
|
144
|
+
return out;
|
|
67
145
|
}
|
|
68
146
|
function resolveMatchedAgentProperties(adAgents, entry) {
|
|
69
147
|
const allProperties = filterRevokedProperties(adAgents.properties, adAgents.revoked_publisher_domains);
|
|
@@ -275,8 +353,10 @@ function allowsLegacyBareInline(adAgents) {
|
|
|
275
353
|
}
|
|
276
354
|
// Annotate the CommonJS export names for ESM import in node:
|
|
277
355
|
0 && (module.exports = {
|
|
356
|
+
agentUrlMatchesAuthorizedEntry,
|
|
278
357
|
canonicalizeAgentUrl,
|
|
279
358
|
getAllProperties,
|
|
280
359
|
listAgentPropertyMap,
|
|
281
|
-
resolveAgentProperties
|
|
360
|
+
resolveAgentProperties,
|
|
361
|
+
usesOriginOnlyAgentMatching
|
|
282
362
|
});
|