@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
@@ -18,13 +18,19 @@ 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
+ resolvePublisherSigningKeyPin: () => resolvePublisherSigningKeyPin,
27
+ usesOriginOnlyAgentMatching: () => usesOriginOnlyAgentMatching
25
28
  });
26
29
  module.exports = __toCommonJS(resolve_agent_properties_exports);
27
30
  var import_inline_publisher_properties = require('./inline-publisher-properties.js');
31
+ var import_version = require('../version.js');
32
+ var import_adcp_version_config = require('../utils/adcp-version-config.js');
33
+ const ORIGIN_ONLY_AGENT_MATCHING_SINCE = "3.3.0-beta.0";
28
34
  function canonicalizeAgentUrl(raw) {
29
35
  const parsed = parseAgentUrl(raw);
30
36
  if (!parsed) return null;
@@ -33,6 +39,38 @@ function canonicalizeAgentUrl(raw) {
33
39
  const query = parsed.search ? decodeUnreservedPercentEncoding(parsed.search) : fragmentlessHref.endsWith("?") ? "?" : "";
34
40
  return `${parsed.protocol}//${parsed.host}${path}${query}`;
35
41
  }
42
+ function canonicalAgentUrlParts(raw) {
43
+ const url = canonicalizeAgentUrl(raw);
44
+ if (url === null) return null;
45
+ const parsed = new URL(url);
46
+ const origin = `${parsed.protocol}//${parsed.host}`;
47
+ return { url, originOnly: url === `${origin}/`, rootDotless: stripRootDot(parsed, url, origin) };
48
+ }
49
+ function stripRootDot(parsed, url, origin) {
50
+ const host = parsed.hostname;
51
+ if (host.startsWith("[") || !host.endsWith(".")) return { url, origin };
52
+ if (host.endsWith("..") || host === ".") return null;
53
+ const dotless = `${parsed.protocol}//${host.slice(0, -1)}${parsed.port ? `:${parsed.port}` : ""}`;
54
+ return { url: dotless + url.slice(origin.length), origin: dotless };
55
+ }
56
+ function usesOriginOnlyAgentMatching(adcpVersion = import_version.ADCP_VERSION) {
57
+ return (0, import_adcp_version_config.isAdcpVersionAtLeast)(adcpVersion, ORIGIN_ONLY_AGENT_MATCHING_SINCE);
58
+ }
59
+ function agentUrlMatchesAuthorizedEntry(entryUrl, agentUrl, options = {}) {
60
+ const entry = canonicalAgentUrlParts(entryUrl);
61
+ const agent = canonicalAgentUrlParts(agentUrl);
62
+ if (!entry || !agent) return false;
63
+ return matchCanonicalAgentUrl(entry, agent, usesOriginOnlyAgentMatching(options.adcpVersion)) !== "none";
64
+ }
65
+ function matchCanonicalAgentUrl(entry, agent, originOnlyMatching) {
66
+ if (!originOnlyMatching) return entry.url === agent.url ? "exact" : "none";
67
+ const e = entry.rootDotless;
68
+ const a = agent.rootDotless;
69
+ if (!e || !a) return "none";
70
+ if (e.url === a.url) return "exact";
71
+ if (entry.originOnly && e.origin === a.origin) return "origin";
72
+ return "none";
73
+ }
36
74
  function parseAgentUrl(raw) {
37
75
  if (typeof raw !== "string" || raw.length === 0) return null;
38
76
  let parsed;
@@ -45,25 +83,125 @@ function parseAgentUrl(raw) {
45
83
  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
46
84
  return parsed;
47
85
  }
48
- function resolveAgentProperties(adAgents, agentUrl) {
49
- const wanted = canonicalizeAgentUrl(agentUrl);
86
+ function resolveAgentProperties(adAgents, agentUrl, options = {}) {
87
+ const wanted = canonicalAgentUrlParts(agentUrl);
50
88
  if (!wanted) {
51
89
  return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
52
90
  }
91
+ const originOnlyMatching = usesOriginOnlyAgentMatching(options.adcpVersion);
53
92
  const entries = Array.isArray(adAgents.authorized_agents) ? adAgents.authorized_agents : [];
54
- const matches = entries.filter((e) => {
55
- if (!e || typeof e.url !== "string") return false;
56
- const canon = canonicalizeAgentUrl(e.url);
57
- return canon !== null && canon === wanted;
58
- });
59
- if (matches.length > 1) {
60
- return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
93
+ const matches = [];
94
+ for (const e of entries) {
95
+ if (!e || typeof e.url !== "string") continue;
96
+ const canon = canonicalAgentUrlParts(e.url);
97
+ if (!canon) continue;
98
+ if (matchCanonicalAgentUrl(canon, wanted, originOnlyMatching) !== "none") matches.push(e);
61
99
  }
62
- const entry = matches[0];
63
- if (!entry) {
100
+ const first = matches[0];
101
+ if (!first) {
64
102
  return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
65
103
  }
66
- return resolveMatchedAgentProperties(adAgents, entry);
104
+ if (!originOnlyMatching) {
105
+ if (matches.length > 1) {
106
+ return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
107
+ }
108
+ return resolveMatchedAgentProperties(adAgents, first);
109
+ }
110
+ if (matches.length === 1) {
111
+ return { ...resolveMatchedAgentProperties(adAgents, first), matched_entries: [first] };
112
+ }
113
+ return unionAgentScopes(
114
+ matches.map((entry) => resolveMatchedAgentProperties(adAgents, entry)),
115
+ matches
116
+ );
117
+ }
118
+ function resolvePublisherSigningKeyPin(adAgents, agentUrl, options = {}) {
119
+ const NOT_AUTHORIZED = [];
120
+ const wanted = canonicalAgentUrlParts(agentUrl);
121
+ if (!wanted) return NOT_AUTHORIZED;
122
+ const originOnlyMatching = usesOriginOnlyAgentMatching(options.adcpVersion);
123
+ const entries = Array.isArray(adAgents.authorized_agents) ? adAgents.authorized_agents : [];
124
+ const matching = entries.filter((entry) => {
125
+ if (!entry || typeof entry !== "object" || typeof entry.url !== "string") return false;
126
+ const canon = canonicalAgentUrlParts(entry.url);
127
+ return canon !== null && matchCanonicalAgentUrl(canon, wanted, originOnlyMatching) !== "none";
128
+ });
129
+ if (!originOnlyMatching && matching.length > 1) return NOT_AUTHORIZED;
130
+ const at = options.at === void 0 ? Date.now() : new Date(options.at).getTime();
131
+ const country = options.country?.toUpperCase();
132
+ const authorizing = matching.filter((entry) => withinEffectiveWindow(entry, at) && coversCountry(entry, country)).map((entry) => ({ entry, scope: resolveMatchedAgentProperties(adAgents, entry) })).filter(({ scope }) => scope.properties.length > 0 || scope.cross_publisher.length > 0);
133
+ if (authorizing.length === 0) return NOT_AUTHORIZED;
134
+ if (!options.propertyIds?.length) {
135
+ return combineEntryPins(authorizing.map(({ entry }) => entry));
136
+ }
137
+ const perProperty = [];
138
+ for (const propertyId of new Set(options.propertyIds)) {
139
+ const covering = authorizing.filter(({ scope }) => scope.properties.some((p) => p.property_id === propertyId));
140
+ if (covering.length === 0) return NOT_AUTHORIZED;
141
+ perProperty.push(combineEntryPins(covering.map(({ entry }) => entry)));
142
+ }
143
+ return intersectPins(perProperty);
144
+ }
145
+ function combineEntryPins(entries) {
146
+ if (!entries.every((entry) => Array.isArray(entry.signing_keys) && entry.signing_keys.length > 0)) return void 0;
147
+ return uniqueByValue(entries.flatMap((entry) => entry.signing_keys));
148
+ }
149
+ function intersectPins(pins) {
150
+ const pinned = pins.filter((pin) => pin !== void 0);
151
+ if (pinned.length === 0) return void 0;
152
+ const identity = (key) => {
153
+ const { revoked_at: _revokedAt, ...rest } = key ?? {};
154
+ return JSON.stringify(
155
+ Object.keys(rest).sort().map((name) => [name, rest[name]])
156
+ );
157
+ };
158
+ const shared = pinned.map((pin) => new Set(pin.map(identity))).reduce((acc, ids) => new Set([...acc].filter((id) => ids.has(id))));
159
+ return uniqueByValue(pinned.flatMap((pin) => pin.filter((key) => shared.has(identity(key)))));
160
+ }
161
+ function withinEffectiveWindow(entry, at) {
162
+ if (Number.isNaN(at)) return false;
163
+ if (entry.effective_from !== void 0) {
164
+ const from = Date.parse(entry.effective_from);
165
+ if (Number.isNaN(from) || at < from) return false;
166
+ }
167
+ if (entry.effective_until !== void 0) {
168
+ const until = Date.parse(entry.effective_until);
169
+ if (Number.isNaN(until) || at > until) return false;
170
+ }
171
+ return true;
172
+ }
173
+ function coversCountry(entry, country) {
174
+ if (!Array.isArray(entry.countries) || entry.countries.length === 0) return true;
175
+ return country !== void 0 && entry.countries.some((c) => typeof c === "string" && c.toUpperCase() === country);
176
+ }
177
+ function unionAgentScopes(scopes, entries) {
178
+ const properties = uniqueByValue(scopes.flatMap((s) => s.properties));
179
+ const cross_publisher = uniqueByValue(scopes.flatMap((s) => s.cross_publisher));
180
+ const cross_publisher_expanded = uniqueByValue(scopes.flatMap((s) => s.cross_publisher_expanded));
181
+ const empty = properties.length === 0 && cross_publisher.length === 0;
182
+ const reason = scopes.find((s) => s.unresolvable !== void 0)?.unresolvable;
183
+ return {
184
+ properties,
185
+ cross_publisher,
186
+ cross_publisher_expanded,
187
+ matched_entry: entries[0],
188
+ matched_entries: entries,
189
+ ...empty && reason !== void 0 ? { unresolvable: reason } : {}
190
+ };
191
+ }
192
+ function uniqueByValue(items) {
193
+ const seenRefs = /* @__PURE__ */ new Set();
194
+ const seenValues = /* @__PURE__ */ new Set();
195
+ const out = [];
196
+ for (const item of items) {
197
+ if (seenRefs.has(item)) continue;
198
+ seenRefs.add(item);
199
+ const value = JSON.stringify(item);
200
+ if (seenValues.has(value)) continue;
201
+ seenValues.add(value);
202
+ out.push(item);
203
+ }
204
+ return out;
67
205
  }
68
206
  function resolveMatchedAgentProperties(adAgents, entry) {
69
207
  const allProperties = filterRevokedProperties(adAgents.properties, adAgents.revoked_publisher_domains);
@@ -275,8 +413,11 @@ function allowsLegacyBareInline(adAgents) {
275
413
  }
276
414
  // Annotate the CommonJS export names for ESM import in node:
277
415
  0 && (module.exports = {
416
+ agentUrlMatchesAuthorizedEntry,
278
417
  canonicalizeAgentUrl,
279
418
  getAllProperties,
280
419
  listAgentPropertyMap,
281
- resolveAgentProperties
420
+ resolveAgentProperties,
421
+ resolvePublisherSigningKeyPin,
422
+ usesOriginOnlyAgentMatching
282
423
  });
@@ -1,4 +1,7 @@
1
1
  import { resolveInlinePublisherProperties } from "./inline-publisher-properties.mjs";
2
+ import { ADCP_VERSION } from "../version.mjs";
3
+ import { isAdcpVersionAtLeast } from "../utils/adcp-version-config.mjs";
4
+ const ORIGIN_ONLY_AGENT_MATCHING_SINCE = "3.3.0-beta.0";
2
5
  function canonicalizeAgentUrl(raw) {
3
6
  const parsed = parseAgentUrl(raw);
4
7
  if (!parsed) return null;
@@ -7,6 +10,38 @@ function canonicalizeAgentUrl(raw) {
7
10
  const query = parsed.search ? decodeUnreservedPercentEncoding(parsed.search) : fragmentlessHref.endsWith("?") ? "?" : "";
8
11
  return `${parsed.protocol}//${parsed.host}${path}${query}`;
9
12
  }
13
+ function canonicalAgentUrlParts(raw) {
14
+ const url = canonicalizeAgentUrl(raw);
15
+ if (url === null) return null;
16
+ const parsed = new URL(url);
17
+ const origin = `${parsed.protocol}//${parsed.host}`;
18
+ return { url, originOnly: url === `${origin}/`, rootDotless: stripRootDot(parsed, url, origin) };
19
+ }
20
+ function stripRootDot(parsed, url, origin) {
21
+ const host = parsed.hostname;
22
+ if (host.startsWith("[") || !host.endsWith(".")) return { url, origin };
23
+ if (host.endsWith("..") || host === ".") return null;
24
+ const dotless = `${parsed.protocol}//${host.slice(0, -1)}${parsed.port ? `:${parsed.port}` : ""}`;
25
+ return { url: dotless + url.slice(origin.length), origin: dotless };
26
+ }
27
+ function usesOriginOnlyAgentMatching(adcpVersion = ADCP_VERSION) {
28
+ return isAdcpVersionAtLeast(adcpVersion, ORIGIN_ONLY_AGENT_MATCHING_SINCE);
29
+ }
30
+ function agentUrlMatchesAuthorizedEntry(entryUrl, agentUrl, options = {}) {
31
+ const entry = canonicalAgentUrlParts(entryUrl);
32
+ const agent = canonicalAgentUrlParts(agentUrl);
33
+ if (!entry || !agent) return false;
34
+ return matchCanonicalAgentUrl(entry, agent, usesOriginOnlyAgentMatching(options.adcpVersion)) !== "none";
35
+ }
36
+ function matchCanonicalAgentUrl(entry, agent, originOnlyMatching) {
37
+ if (!originOnlyMatching) return entry.url === agent.url ? "exact" : "none";
38
+ const e = entry.rootDotless;
39
+ const a = agent.rootDotless;
40
+ if (!e || !a) return "none";
41
+ if (e.url === a.url) return "exact";
42
+ if (entry.originOnly && e.origin === a.origin) return "origin";
43
+ return "none";
44
+ }
10
45
  function parseAgentUrl(raw) {
11
46
  if (typeof raw !== "string" || raw.length === 0) return null;
12
47
  let parsed;
@@ -19,25 +54,125 @@ function parseAgentUrl(raw) {
19
54
  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
20
55
  return parsed;
21
56
  }
22
- function resolveAgentProperties(adAgents, agentUrl) {
23
- const wanted = canonicalizeAgentUrl(agentUrl);
57
+ function resolveAgentProperties(adAgents, agentUrl, options = {}) {
58
+ const wanted = canonicalAgentUrlParts(agentUrl);
24
59
  if (!wanted) {
25
60
  return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
26
61
  }
62
+ const originOnlyMatching = usesOriginOnlyAgentMatching(options.adcpVersion);
27
63
  const entries = Array.isArray(adAgents.authorized_agents) ? adAgents.authorized_agents : [];
28
- const matches = entries.filter((e) => {
29
- if (!e || typeof e.url !== "string") return false;
30
- const canon = canonicalizeAgentUrl(e.url);
31
- return canon !== null && canon === wanted;
32
- });
33
- if (matches.length > 1) {
34
- return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
64
+ const matches = [];
65
+ for (const e of entries) {
66
+ if (!e || typeof e.url !== "string") continue;
67
+ const canon = canonicalAgentUrlParts(e.url);
68
+ if (!canon) continue;
69
+ if (matchCanonicalAgentUrl(canon, wanted, originOnlyMatching) !== "none") matches.push(e);
35
70
  }
36
- const entry = matches[0];
37
- if (!entry) {
71
+ const first = matches[0];
72
+ if (!first) {
38
73
  return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
39
74
  }
40
- return resolveMatchedAgentProperties(adAgents, entry);
75
+ if (!originOnlyMatching) {
76
+ if (matches.length > 1) {
77
+ return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
78
+ }
79
+ return resolveMatchedAgentProperties(adAgents, first);
80
+ }
81
+ if (matches.length === 1) {
82
+ return { ...resolveMatchedAgentProperties(adAgents, first), matched_entries: [first] };
83
+ }
84
+ return unionAgentScopes(
85
+ matches.map((entry) => resolveMatchedAgentProperties(adAgents, entry)),
86
+ matches
87
+ );
88
+ }
89
+ function resolvePublisherSigningKeyPin(adAgents, agentUrl, options = {}) {
90
+ const NOT_AUTHORIZED = [];
91
+ const wanted = canonicalAgentUrlParts(agentUrl);
92
+ if (!wanted) return NOT_AUTHORIZED;
93
+ const originOnlyMatching = usesOriginOnlyAgentMatching(options.adcpVersion);
94
+ const entries = Array.isArray(adAgents.authorized_agents) ? adAgents.authorized_agents : [];
95
+ const matching = entries.filter((entry) => {
96
+ if (!entry || typeof entry !== "object" || typeof entry.url !== "string") return false;
97
+ const canon = canonicalAgentUrlParts(entry.url);
98
+ return canon !== null && matchCanonicalAgentUrl(canon, wanted, originOnlyMatching) !== "none";
99
+ });
100
+ if (!originOnlyMatching && matching.length > 1) return NOT_AUTHORIZED;
101
+ const at = options.at === void 0 ? Date.now() : new Date(options.at).getTime();
102
+ const country = options.country?.toUpperCase();
103
+ const authorizing = matching.filter((entry) => withinEffectiveWindow(entry, at) && coversCountry(entry, country)).map((entry) => ({ entry, scope: resolveMatchedAgentProperties(adAgents, entry) })).filter(({ scope }) => scope.properties.length > 0 || scope.cross_publisher.length > 0);
104
+ if (authorizing.length === 0) return NOT_AUTHORIZED;
105
+ if (!options.propertyIds?.length) {
106
+ return combineEntryPins(authorizing.map(({ entry }) => entry));
107
+ }
108
+ const perProperty = [];
109
+ for (const propertyId of new Set(options.propertyIds)) {
110
+ const covering = authorizing.filter(({ scope }) => scope.properties.some((p) => p.property_id === propertyId));
111
+ if (covering.length === 0) return NOT_AUTHORIZED;
112
+ perProperty.push(combineEntryPins(covering.map(({ entry }) => entry)));
113
+ }
114
+ return intersectPins(perProperty);
115
+ }
116
+ function combineEntryPins(entries) {
117
+ if (!entries.every((entry) => Array.isArray(entry.signing_keys) && entry.signing_keys.length > 0)) return void 0;
118
+ return uniqueByValue(entries.flatMap((entry) => entry.signing_keys));
119
+ }
120
+ function intersectPins(pins) {
121
+ const pinned = pins.filter((pin) => pin !== void 0);
122
+ if (pinned.length === 0) return void 0;
123
+ const identity = (key) => {
124
+ const { revoked_at: _revokedAt, ...rest } = key ?? {};
125
+ return JSON.stringify(
126
+ Object.keys(rest).sort().map((name) => [name, rest[name]])
127
+ );
128
+ };
129
+ const shared = pinned.map((pin) => new Set(pin.map(identity))).reduce((acc, ids) => new Set([...acc].filter((id) => ids.has(id))));
130
+ return uniqueByValue(pinned.flatMap((pin) => pin.filter((key) => shared.has(identity(key)))));
131
+ }
132
+ function withinEffectiveWindow(entry, at) {
133
+ if (Number.isNaN(at)) return false;
134
+ if (entry.effective_from !== void 0) {
135
+ const from = Date.parse(entry.effective_from);
136
+ if (Number.isNaN(from) || at < from) return false;
137
+ }
138
+ if (entry.effective_until !== void 0) {
139
+ const until = Date.parse(entry.effective_until);
140
+ if (Number.isNaN(until) || at > until) return false;
141
+ }
142
+ return true;
143
+ }
144
+ function coversCountry(entry, country) {
145
+ if (!Array.isArray(entry.countries) || entry.countries.length === 0) return true;
146
+ return country !== void 0 && entry.countries.some((c) => typeof c === "string" && c.toUpperCase() === country);
147
+ }
148
+ function unionAgentScopes(scopes, entries) {
149
+ const properties = uniqueByValue(scopes.flatMap((s) => s.properties));
150
+ const cross_publisher = uniqueByValue(scopes.flatMap((s) => s.cross_publisher));
151
+ const cross_publisher_expanded = uniqueByValue(scopes.flatMap((s) => s.cross_publisher_expanded));
152
+ const empty = properties.length === 0 && cross_publisher.length === 0;
153
+ const reason = scopes.find((s) => s.unresolvable !== void 0)?.unresolvable;
154
+ return {
155
+ properties,
156
+ cross_publisher,
157
+ cross_publisher_expanded,
158
+ matched_entry: entries[0],
159
+ matched_entries: entries,
160
+ ...empty && reason !== void 0 ? { unresolvable: reason } : {}
161
+ };
162
+ }
163
+ function uniqueByValue(items) {
164
+ const seenRefs = /* @__PURE__ */ new Set();
165
+ const seenValues = /* @__PURE__ */ new Set();
166
+ const out = [];
167
+ for (const item of items) {
168
+ if (seenRefs.has(item)) continue;
169
+ seenRefs.add(item);
170
+ const value = JSON.stringify(item);
171
+ if (seenValues.has(value)) continue;
172
+ seenValues.add(value);
173
+ out.push(item);
174
+ }
175
+ return out;
41
176
  }
42
177
  function resolveMatchedAgentProperties(adAgents, entry) {
43
178
  const allProperties = filterRevokedProperties(adAgents.properties, adAgents.revoked_publisher_domains);
@@ -248,8 +383,11 @@ function allowsLegacyBareInline(adAgents) {
248
383
  return typeof adAgents.$schema !== "string" || adAgents.$schema.length === 0;
249
384
  }
250
385
  export {
386
+ agentUrlMatchesAuthorizedEntry,
251
387
  canonicalizeAgentUrl,
252
388
  getAllProperties,
253
389
  listAgentPropertyMap,
254
- resolveAgentProperties
390
+ resolveAgentProperties,
391
+ resolvePublisherSigningKeyPin,
392
+ usesOriginOnlyAgentMatching
255
393
  };
@@ -149,6 +149,20 @@ export interface AuthorizedAgent {
149
149
  signal_ids?: string[];
150
150
  /** Selector for `authorization_type: 'signal_tags'` (signals agents). */
151
151
  signal_tags?: string[];
152
+ /** ISO 3166-1 alpha-2 countries this authorization is limited to. */
153
+ countries?: string[];
154
+ /** Start of the authorization's time window (ISO 8601). */
155
+ effective_from?: string;
156
+ /** End of the authorization's time window (ISO 8601). */
157
+ effective_until?: string;
158
+ /**
159
+ * Publisher-attested public keys that narrow the keys this agent may sign
160
+ * with for the publisher's inventory. When several entries match one agent
161
+ * and authorize a message (AdCP 3.3+), combine them with
162
+ * `resolvePublisherSigningKeyPin`: pinned only if every such entry pins,
163
+ * and then the union of their keys (adcontextprotocol/adcp#9016).
164
+ */
165
+ signing_keys?: Record<string, unknown>[];
152
166
  }
153
167
  /**
154
168
  * Per-publisher format declaration inside `adagents.json#/formats`.
@@ -149,6 +149,20 @@ export interface AuthorizedAgent {
149
149
  signal_ids?: string[];
150
150
  /** Selector for `authorization_type: 'signal_tags'` (signals agents). */
151
151
  signal_tags?: string[];
152
+ /** ISO 3166-1 alpha-2 countries this authorization is limited to. */
153
+ countries?: string[];
154
+ /** Start of the authorization's time window (ISO 8601). */
155
+ effective_from?: string;
156
+ /** End of the authorization's time window (ISO 8601). */
157
+ effective_until?: string;
158
+ /**
159
+ * Publisher-attested public keys that narrow the keys this agent may sign
160
+ * with for the publisher's inventory. When several entries match one agent
161
+ * and authorize a message (AdCP 3.3+), combine them with
162
+ * `resolvePublisherSigningKeyPin`: pinned only if every such entry pins,
163
+ * and then the union of their keys (adcontextprotocol/adcp#9016).
164
+ */
165
+ signing_keys?: Record<string, unknown>[];
152
166
  }
153
167
  /**
154
168
  * Per-publisher format declaration inside `adagents.json#/formats`.
@@ -103,6 +103,13 @@ export interface ValidateAdAgentsOptions {
103
103
  /**
104
104
  * Validate `adagents.json` for a publisher domain. Implements the
105
105
  * ads.txt `MANAGERDOMAIN` one-hop fallback specified in adcp#4175.
106
+ *
107
+ * This locates and loads the file; it does not decide whether a given agent
108
+ * is authorized. Check an agent against `result.adagents` with
109
+ * `resolveAgentProperties` or `agentUrlMatchesAuthorizedEntry`, passing the
110
+ * negotiated or targeted `adcpVersion`: at AdCP 3.3 or later an origin-only
111
+ * `authorized_agents[].url` authorizes the agent at any path on that origin
112
+ * (adcp#8862).
106
113
  */
107
114
  export declare function validateAdAgents(publisherDomain: string, options?: ValidateAdAgentsOptions): Promise<AdAgentsValidationResult>;
108
115
  /**
@@ -103,6 +103,13 @@ export interface ValidateAdAgentsOptions {
103
103
  /**
104
104
  * Validate `adagents.json` for a publisher domain. Implements the
105
105
  * ads.txt `MANAGERDOMAIN` one-hop fallback specified in adcp#4175.
106
+ *
107
+ * This locates and loads the file; it does not decide whether a given agent
108
+ * is authorized. Check an agent against `result.adagents` with
109
+ * `resolveAgentProperties` or `agentUrlMatchesAuthorizedEntry`, passing the
110
+ * negotiated or targeted `adcpVersion`: at AdCP 3.3 or later an origin-only
111
+ * `authorized_agents[].url` authorizes the agent at any path on that origin
112
+ * (adcp#8862).
106
113
  */
107
114
  export declare function validateAdAgents(publisherDomain: string, options?: ValidateAdAgentsOptions): Promise<AdAgentsValidationResult>;
108
115
  /**
@@ -2,7 +2,7 @@ export { PropertyIndex, getPropertyIndex, resetPropertyIndex, type PropertyMatch
2
2
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from '../discovery/network-consistency-checker.mjs';
3
3
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from '../discovery/types.mjs';
4
4
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from '../discovery/publisher-property-selector.mjs';
5
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties.mjs';
5
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, resolvePublisherSigningKeyPin, type PublisherSigningKeyPinOptions, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties.mjs';
6
6
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from '../discovery/inline-publisher-properties.mjs';
7
7
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from '../discovery/agent-directory.mjs';
8
8
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from '../discovery/validate-adagents.mjs';
@@ -2,7 +2,7 @@ export { PropertyIndex, getPropertyIndex, resetPropertyIndex, type PropertyMatch
2
2
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from '../discovery/network-consistency-checker';
3
3
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from '../discovery/types';
4
4
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from '../discovery/publisher-property-selector';
5
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties';
5
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, resolvePublisherSigningKeyPin, type PublisherSigningKeyPinOptions, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties';
6
6
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from '../discovery/inline-publisher-properties';
7
7
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from '../discovery/agent-directory';
8
8
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from '../discovery/validate-adagents';
@@ -21,6 +21,7 @@ __export(discovery_exports, {
21
21
  NetworkConsistencyChecker: () => import_network_consistency_checker.NetworkConsistencyChecker,
22
22
  PropertyIndex: () => import_property_index.PropertyIndex,
23
23
  PublisherPropertySelectorParseError: () => import_publisher_property_selector.PublisherPropertySelectorParseError,
24
+ agentUrlMatchesAuthorizedEntry: () => import_resolve_agent_properties.agentUrlMatchesAuthorizedEntry,
24
25
  canonicalizeAgentUrl: () => import_resolve_agent_properties.canonicalizeAgentUrl,
25
26
  detectInlineFederatedDivergence: () => import_inline_publisher_properties.detectInlineFederatedDivergence,
26
27
  expandPublisherPropertySelector: () => import_publisher_property_selector.expandPublisherPropertySelector,
@@ -36,7 +37,9 @@ __export(discovery_exports, {
36
37
  resetPropertyIndex: () => import_property_index.resetPropertyIndex,
37
38
  resolveAgentProperties: () => import_resolve_agent_properties.resolveAgentProperties,
38
39
  resolveInlinePublisherProperties: () => import_inline_publisher_properties.resolveInlinePublisherProperties,
40
+ resolvePublisherSigningKeyPin: () => import_resolve_agent_properties.resolvePublisherSigningKeyPin,
39
41
  resolveSingularInline: () => import_inline_publisher_properties.resolveSingularInline,
42
+ usesOriginOnlyAgentMatching: () => import_resolve_agent_properties.usesOriginOnlyAgentMatching,
40
43
  validateAdAgents: () => import_validate_adagents.validateAdAgents
41
44
  });
42
45
  module.exports = __toCommonJS(discovery_exports);
@@ -52,6 +55,7 @@ var import_validate_adagents = require('../discovery/validate-adagents.js');
52
55
  NetworkConsistencyChecker,
53
56
  PropertyIndex,
54
57
  PublisherPropertySelectorParseError,
58
+ agentUrlMatchesAuthorizedEntry,
55
59
  canonicalizeAgentUrl,
56
60
  detectInlineFederatedDivergence,
57
61
  expandPublisherPropertySelector,
@@ -67,6 +71,8 @@ var import_validate_adagents = require('../discovery/validate-adagents.js');
67
71
  resetPropertyIndex,
68
72
  resolveAgentProperties,
69
73
  resolveInlinePublisherProperties,
74
+ resolvePublisherSigningKeyPin,
70
75
  resolveSingularInline,
76
+ usesOriginOnlyAgentMatching,
71
77
  validateAdAgents
72
78
  });
@@ -18,7 +18,10 @@ import {
18
18
  resolveAgentProperties,
19
19
  listAgentPropertyMap,
20
20
  getAllProperties,
21
- canonicalizeAgentUrl
21
+ canonicalizeAgentUrl,
22
+ agentUrlMatchesAuthorizedEntry,
23
+ usesOriginOnlyAgentMatching,
24
+ resolvePublisherSigningKeyPin
22
25
  } from "../discovery/resolve-agent-properties.mjs";
23
26
  import {
24
27
  resolveInlinePublisherProperties,
@@ -36,6 +39,7 @@ export {
36
39
  NetworkConsistencyChecker,
37
40
  PropertyIndex,
38
41
  PublisherPropertySelectorParseError,
42
+ agentUrlMatchesAuthorizedEntry,
39
43
  canonicalizeAgentUrl,
40
44
  detectInlineFederatedDivergence,
41
45
  expandPublisherPropertySelector,
@@ -51,6 +55,8 @@ export {
51
55
  resetPropertyIndex,
52
56
  resolveAgentProperties,
53
57
  resolveInlinePublisherProperties,
58
+ resolvePublisherSigningKeyPin,
54
59
  resolveSingularInline,
60
+ usesOriginOnlyAgentMatching,
55
61
  validateAdAgents
56
62
  };
@@ -11,7 +11,7 @@ export { PropertyCrawler, type AgentInfo, type CrawlResult, type PropertyCrawler
11
11
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from './discovery/network-consistency-checker.mjs';
12
12
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from './discovery/types.mjs';
13
13
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from './discovery/publisher-property-selector.mjs';
14
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties.mjs';
14
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, resolvePublisherSigningKeyPin, type PublisherSigningKeyPinOptions, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties.mjs';
15
15
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from './discovery/inline-publisher-properties.mjs';
16
16
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from './discovery/agent-directory.mjs';
17
17
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from './discovery/validate-adagents.mjs';
@@ -11,7 +11,7 @@ export { PropertyCrawler, type AgentInfo, type CrawlResult, type PropertyCrawler
11
11
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from './discovery/network-consistency-checker';
12
12
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from './discovery/types';
13
13
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from './discovery/publisher-property-selector';
14
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties';
14
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, resolvePublisherSigningKeyPin, type PublisherSigningKeyPinOptions, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties';
15
15
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from './discovery/inline-publisher-properties';
16
16
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from './discovery/agent-directory';
17
17
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from './discovery/validate-adagents';
package/dist/lib/index.js CHANGED
@@ -239,6 +239,7 @@ __export(index_exports, {
239
239
  addSpanAttributes: () => import_observability.addSpanAttributes,
240
240
  adjustedMediaBuyDeliveryNotification: () => import_media_buy_delivery_notification_builders.adjustedMediaBuyDeliveryNotification,
241
241
  agentSignalId: () => import_signal_id_builders.agentSignalId,
242
+ agentUrlMatchesAuthorizedEntry: () => import_resolve_agent_properties.agentUrlMatchesAuthorizedEntry,
242
243
  applyBrandAssetMappings: () => import_brand.applyBrandAssetMappings,
243
244
  applyTargetingInput: () => import_media_buy.applyTargetingInput,
244
245
  assertCreativeTransition: () => import_server.assertCreativeTransition,
@@ -647,6 +648,7 @@ __export(index_exports, {
647
648
  resolveInlinePublisherProperties: () => import_inline_publisher_properties.resolveInlinePublisherProperties,
648
649
  resolvePlatformExtensionsReference: () => import_canonical_references.resolvePlatformExtensionsReference,
649
650
  resolvePreviewAuthority: () => import_preview_authority.resolvePreviewAuthority,
651
+ resolvePublisherSigningKeyPin: () => import_resolve_agent_properties.resolvePublisherSigningKeyPin,
650
652
  resolveRecovery: () => import_error_extraction.resolveRecovery,
651
653
  resolveSecret: () => import_oauth4.resolveSecret,
652
654
  resolveSingularInline: () => import_inline_publisher_properties.resolveSingularInline,
@@ -715,6 +717,7 @@ __export(index_exports, {
715
717
  urlRender: () => import_render_builders.urlRender,
716
718
  useIdempotencyKey: () => import_idempotency.useIdempotencyKey,
717
719
  usesDeprecatedAssetsField: () => import_format_assets.usesDeprecatedAssetsField,
720
+ usesOriginOnlyAgentMatching: () => import_resolve_agent_properties.usesOriginOnlyAgentMatching,
718
721
  usesV3CreativeAssignments: () => import_creative_adapter.usesV3CreativeAssignments,
719
722
  usesV3RenderFields: () => import_preview_normalizer.usesV3RenderFields,
720
723
  usesV3Renders: () => import_format_renders.usesV3Renders,
@@ -1109,6 +1112,7 @@ function createAdCPClientFromEnv() {
1109
1112
  addSpanAttributes,
1110
1113
  adjustedMediaBuyDeliveryNotification,
1111
1114
  agentSignalId,
1115
+ agentUrlMatchesAuthorizedEntry,
1112
1116
  applyBrandAssetMappings,
1113
1117
  applyTargetingInput,
1114
1118
  assertCreativeTransition,
@@ -1517,6 +1521,7 @@ function createAdCPClientFromEnv() {
1517
1521
  resolveInlinePublisherProperties,
1518
1522
  resolvePlatformExtensionsReference,
1519
1523
  resolvePreviewAuthority,
1524
+ resolvePublisherSigningKeyPin,
1520
1525
  resolveRecovery,
1521
1526
  resolveSecret,
1522
1527
  resolveSingularInline,
@@ -1585,6 +1590,7 @@ function createAdCPClientFromEnv() {
1585
1590
  urlRender,
1586
1591
  useIdempotencyKey,
1587
1592
  usesDeprecatedAssetsField,
1593
+ usesOriginOnlyAgentMatching,
1588
1594
  usesV3CreativeAssignments,
1589
1595
  usesV3RenderFields,
1590
1596
  usesV3Renders,