@adcp/sdk 17.0.0-beta.26 → 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.
@@ -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;
@@ -74,11 +74,28 @@ export interface ResolvedAgentScope {
74
74
  /**
75
75
  * Every entry that matched the agent URL, in document order. At AdCP 3.3 or
76
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.
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.
82
99
  */
83
100
  matched_entries?: AuthorizedAgent[];
84
101
  /** Why the resolution returned an empty result, when it did. */
@@ -171,6 +188,78 @@ export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUr
171
188
  * malformed, or when the agent uses a signals authorization type.
172
189
  */
173
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;
174
263
  /**
175
264
  * Convenience: list every locally-resolvable (`agent_url` →
176
265
  * `Property[]`) pair from an `adagents.json` file. Agents listed with
@@ -74,11 +74,28 @@ export interface ResolvedAgentScope {
74
74
  /**
75
75
  * Every entry that matched the agent URL, in document order. At AdCP 3.3 or
76
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.
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.
82
99
  */
83
100
  matched_entries?: AuthorizedAgent[];
84
101
  /** Why the resolution returned an empty result, when it did. */
@@ -171,6 +188,78 @@ export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUr
171
188
  * malformed, or when the agent uses a signals authorization type.
172
189
  */
173
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;
174
263
  /**
175
264
  * Convenience: list every locally-resolvable (`agent_url` →
176
265
  * `Property[]`) pair from an `adagents.json` file. Agents listed with
@@ -23,6 +23,7 @@ __export(resolve_agent_properties_exports, {
23
23
  getAllProperties: () => getAllProperties,
24
24
  listAgentPropertyMap: () => listAgentPropertyMap,
25
25
  resolveAgentProperties: () => resolveAgentProperties,
26
+ resolvePublisherSigningKeyPin: () => resolvePublisherSigningKeyPin,
26
27
  usesOriginOnlyAgentMatching: () => usesOriginOnlyAgentMatching
27
28
  });
28
29
  module.exports = __toCommonJS(resolve_agent_properties_exports);
@@ -114,6 +115,65 @@ function resolveAgentProperties(adAgents, agentUrl, options = {}) {
114
115
  matches
115
116
  );
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
+ }
117
177
  function unionAgentScopes(scopes, entries) {
118
178
  const properties = uniqueByValue(scopes.flatMap((s) => s.properties));
119
179
  const cross_publisher = uniqueByValue(scopes.flatMap((s) => s.cross_publisher));
@@ -358,5 +418,6 @@ function allowsLegacyBareInline(adAgents) {
358
418
  getAllProperties,
359
419
  listAgentPropertyMap,
360
420
  resolveAgentProperties,
421
+ resolvePublisherSigningKeyPin,
361
422
  usesOriginOnlyAgentMatching
362
423
  });
@@ -86,6 +86,65 @@ function resolveAgentProperties(adAgents, agentUrl, options = {}) {
86
86
  matches
87
87
  );
88
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
+ }
89
148
  function unionAgentScopes(scopes, entries) {
90
149
  const properties = uniqueByValue(scopes.flatMap((s) => s.properties));
91
150
  const cross_publisher = uniqueByValue(scopes.flatMap((s) => s.cross_publisher));
@@ -329,5 +388,6 @@ export {
329
388
  getAllProperties,
330
389
  listAgentPropertyMap,
331
390
  resolveAgentProperties,
391
+ resolvePublisherSigningKeyPin,
332
392
  usesOriginOnlyAgentMatching
333
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`.
@@ -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, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, 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, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, 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';
@@ -37,6 +37,7 @@ __export(discovery_exports, {
37
37
  resetPropertyIndex: () => import_property_index.resetPropertyIndex,
38
38
  resolveAgentProperties: () => import_resolve_agent_properties.resolveAgentProperties,
39
39
  resolveInlinePublisherProperties: () => import_inline_publisher_properties.resolveInlinePublisherProperties,
40
+ resolvePublisherSigningKeyPin: () => import_resolve_agent_properties.resolvePublisherSigningKeyPin,
40
41
  resolveSingularInline: () => import_inline_publisher_properties.resolveSingularInline,
41
42
  usesOriginOnlyAgentMatching: () => import_resolve_agent_properties.usesOriginOnlyAgentMatching,
42
43
  validateAdAgents: () => import_validate_adagents.validateAdAgents
@@ -70,6 +71,7 @@ var import_validate_adagents = require('../discovery/validate-adagents.js');
70
71
  resetPropertyIndex,
71
72
  resolveAgentProperties,
72
73
  resolveInlinePublisherProperties,
74
+ resolvePublisherSigningKeyPin,
73
75
  resolveSingularInline,
74
76
  usesOriginOnlyAgentMatching,
75
77
  validateAdAgents
@@ -20,7 +20,8 @@ import {
20
20
  getAllProperties,
21
21
  canonicalizeAgentUrl,
22
22
  agentUrlMatchesAuthorizedEntry,
23
- usesOriginOnlyAgentMatching
23
+ usesOriginOnlyAgentMatching,
24
+ resolvePublisherSigningKeyPin
24
25
  } from "../discovery/resolve-agent-properties.mjs";
25
26
  import {
26
27
  resolveInlinePublisherProperties,
@@ -54,6 +55,7 @@ export {
54
55
  resetPropertyIndex,
55
56
  resolveAgentProperties,
56
57
  resolveInlinePublisherProperties,
58
+ resolvePublisherSigningKeyPin,
57
59
  resolveSingularInline,
58
60
  usesOriginOnlyAgentMatching,
59
61
  validateAdAgents
@@ -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, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, 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, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, 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
@@ -648,6 +648,7 @@ __export(index_exports, {
648
648
  resolveInlinePublisherProperties: () => import_inline_publisher_properties.resolveInlinePublisherProperties,
649
649
  resolvePlatformExtensionsReference: () => import_canonical_references.resolvePlatformExtensionsReference,
650
650
  resolvePreviewAuthority: () => import_preview_authority.resolvePreviewAuthority,
651
+ resolvePublisherSigningKeyPin: () => import_resolve_agent_properties.resolvePublisherSigningKeyPin,
651
652
  resolveRecovery: () => import_error_extraction.resolveRecovery,
652
653
  resolveSecret: () => import_oauth4.resolveSecret,
653
654
  resolveSingularInline: () => import_inline_publisher_properties.resolveSingularInline,
@@ -1520,6 +1521,7 @@ function createAdCPClientFromEnv() {
1520
1521
  resolveInlinePublisherProperties,
1521
1522
  resolvePlatformExtensionsReference,
1522
1523
  resolvePreviewAuthority,
1524
+ resolvePublisherSigningKeyPin,
1523
1525
  resolveRecovery,
1524
1526
  resolveSecret,
1525
1527
  resolveSingularInline,
@@ -59,7 +59,8 @@ import {
59
59
  getAllProperties,
60
60
  canonicalizeAgentUrl,
61
61
  agentUrlMatchesAuthorizedEntry,
62
- usesOriginOnlyAgentMatching
62
+ usesOriginOnlyAgentMatching,
63
+ resolvePublisherSigningKeyPin
63
64
  } from "./discovery/resolve-agent-properties.mjs";
64
65
  import {
65
66
  resolveInlinePublisherProperties,
@@ -1479,6 +1480,7 @@ export {
1479
1480
  resolveInlinePublisherProperties,
1480
1481
  resolvePlatformExtensionsReference,
1481
1482
  resolvePreviewAuthority,
1483
+ resolvePublisherSigningKeyPin,
1482
1484
  resolveRecovery,
1483
1485
  resolveSecret,
1484
1486
  resolveSingularInline,
@@ -544,7 +544,7 @@ export interface paths {
544
544
  };
545
545
  /**
546
546
  * Agent domain lookup
547
- * @description Get all publisher domains associated with an agent.
547
+ * @description Get all publisher domains whose adagents.json authorizes an agent. `agentUrl` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule: an origin-only `authorized_agents[].url` (`https://agent.example.com`) authorizes every agent URL at that origin, and an entry with a path matches that canonical URL only, with a non-root trailing slash significant.
548
548
  */
549
549
  get: operations["getAgentDomains"];
550
550
  put?: never;
@@ -568,7 +568,7 @@ export interface paths {
568
568
  *
569
569
  * Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
570
570
  *
571
- * `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
571
+ * `agent_url` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule, after [AdCP URL canonicalization](/docs/reference/url-canonicalization) of both sides. A publisher whose `authorized_agents[].url` is **origin-only** (`https://a.example` or `https://a.example/`) authorizes every agent URL with that canonical origin (same scheme, host and port), so it is returned for `https://a.example/mcp` and `https://a.example/a2a` alike (DR-0023, AdCP 3.3). An entry **with a path** matches that canonical URL only, and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two trailing-slash spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
572
572
  */
573
573
  get: operations["getPublishersForAgentLegacyApiPrefix"];
574
574
  put?: never;
@@ -592,7 +592,7 @@ export interface paths {
592
592
  *
593
593
  * Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
594
594
  *
595
- * `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
595
+ * `agent_url` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule, after [AdCP URL canonicalization](/docs/reference/url-canonicalization) of both sides. A publisher whose `authorized_agents[].url` is **origin-only** (`https://a.example` or `https://a.example/`) authorizes every agent URL with that canonical origin (same scheme, host and port), so it is returned for `https://a.example/mcp` and `https://a.example/a2a` alike (DR-0023, AdCP 3.3). An entry **with a path** matches that canonical URL only, and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two trailing-slash spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
596
596
  */
597
597
  get: operations["getPublishersForAgent"];
598
598
  put?: never;
@@ -2582,7 +2582,7 @@ export interface components {
2582
2582
  stats?: components["schemas"]["AgentStats"];
2583
2583
  capabilities?: components["schemas"]["AgentCapabilities"];
2584
2584
  compliance?: components["schemas"]["AgentCompliance"];
2585
- /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches spec-exactly with the slash significant — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. */
2585
+ /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches with adagents.json agent URL matching, where the slash is significant for an entry with a path — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. Publishers that authorize the agent's bare origin are returned for every spelling. */
2586
2586
  declared_urls?: string[];
2587
2587
  publisher_domains?: string[];
2588
2588
  property_summary?: components["schemas"]["PropertySummary"];
@@ -8781,7 +8781,7 @@ export interface operations {
8781
8781
  getAgentAuthorizations: {
8782
8782
  parameters: {
8783
8783
  query: {
8784
- /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
8784
+ /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. Returns the rows whose `agent_url` authorizes it under adagents.json agent URL matching: rows for the same canonical URL, plus rows whose `agent_url` is origin-only (`https://agent.example.com`) for the same canonical origin, which authorize every path at that origin. */
8785
8785
  agent_url: string;
8786
8786
  /** @description `effective` (default) applies override layer; `raw` reads base table. */
8787
8787
  include?: "raw" | "effective";
@@ -569,6 +569,13 @@ const NEUTRAL_BUNDLE_SKIP_REASONS = /* @__PURE__ */ new Set([
569
569
  "capability_prerequisite_unavailable"
570
570
  ]);
571
571
  const CAPABILITY_ROLLUP_MIN_ADCP_VERSION = "3.2";
572
+ const CAPABILITY_ROLLUP_MIN_3_1_PATCH = 24;
573
+ const STABLE_3_1_RELEASE_PATTERN = /^3\.1\.(\d+)$/;
574
+ function carriesApplicabilityOrderRule(adcpVersion) {
575
+ if (compareAdcpVersionStrings(adcpVersion, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) >= 0) return true;
576
+ const patch = STABLE_3_1_RELEASE_PATTERN.exec(adcpVersion)?.[1];
577
+ return patch !== void 0 && Number.parseInt(patch, 10) >= CAPABILITY_ROLLUP_MIN_3_1_PATCH;
578
+ }
572
579
  const CAPABILITY_UNSUPPORTED_ROW_ID = "capability_unsupported";
573
580
  const CAPABILITY_UNSUPPORTED_RESULT_KEYS = /* @__PURE__ */ new Set([
574
581
  "storyboard_id",
@@ -616,7 +623,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
616
623
  const predicates = (0, import_runner.storyboardCapabilityPredicates)(storyboard);
617
624
  if (predicates.length === 0) return false;
618
625
  if (typeof storyboard.adcp_version !== "string") return false;
619
- if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
626
+ if (!carriesApplicabilityOrderRule(storyboard.adcp_version)) return false;
620
627
  if (predicates.flatMap(import_runner.capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
621
628
  return false;
622
629
  }
@@ -563,6 +563,13 @@ const NEUTRAL_BUNDLE_SKIP_REASONS = /* @__PURE__ */ new Set([
563
563
  "capability_prerequisite_unavailable"
564
564
  ]);
565
565
  const CAPABILITY_ROLLUP_MIN_ADCP_VERSION = "3.2";
566
+ const CAPABILITY_ROLLUP_MIN_3_1_PATCH = 24;
567
+ const STABLE_3_1_RELEASE_PATTERN = /^3\.1\.(\d+)$/;
568
+ function carriesApplicabilityOrderRule(adcpVersion) {
569
+ if (compareAdcpVersionStrings(adcpVersion, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) >= 0) return true;
570
+ const patch = STABLE_3_1_RELEASE_PATTERN.exec(adcpVersion)?.[1];
571
+ return patch !== void 0 && Number.parseInt(patch, 10) >= CAPABILITY_ROLLUP_MIN_3_1_PATCH;
572
+ }
566
573
  const CAPABILITY_UNSUPPORTED_ROW_ID = "capability_unsupported";
567
574
  const CAPABILITY_UNSUPPORTED_RESULT_KEYS = /* @__PURE__ */ new Set([
568
575
  "storyboard_id",
@@ -610,7 +617,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
610
617
  const predicates = storyboardCapabilityPredicates(storyboard);
611
618
  if (predicates.length === 0) return false;
612
619
  if (typeof storyboard.adcp_version !== "string") return false;
613
- if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
620
+ if (!carriesApplicabilityOrderRule(storyboard.adcp_version)) return false;
614
621
  if (predicates.flatMap(capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
615
622
  return false;
616
623
  }
@@ -200,7 +200,7 @@ export interface UpstreamTrafficQueryResult {
200
200
  */
201
201
  export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
202
202
  /** Capability semver emitted in run summaries and used for advisory expiry. */
203
- export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.26";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.27";
204
204
  /** True when a failed validation contributes to the owning step's grade. */
205
205
  export declare function validationFailsStep(result: ValidationResult): boolean;
206
206
  /**
@@ -200,7 +200,7 @@ export interface UpstreamTrafficQueryResult {
200
200
  */
201
201
  export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
202
202
  /** Capability semver emitted in run summaries and used for advisory expiry. */
203
- export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.26";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.27";
204
204
  /** True when a failed validation contributes to the owning step's grade. */
205
205
  export declare function validationFailsStep(result: ValidationResult): boolean;
206
206
  /**
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.26";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.27";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.26";
36
+ readonly library: "17.0.0-beta.27";
37
37
  readonly adcp: "3.3.0-beta.6";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.6", "3.3-beta.6"];
39
- readonly generatedAt: "2026-11-14T15:52:16.390Z";
39
+ readonly generatedAt: "2026-11-14T21:58:26.439Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.26";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.27";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.26";
36
+ readonly library: "17.0.0-beta.27";
37
37
  readonly adcp: "3.3.0-beta.6";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.6", "3.3-beta.6"];
39
- readonly generatedAt: "2026-11-14T15:52:16.390Z";
39
+ readonly generatedAt: "2026-11-14T21:58:26.439Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -31,7 +31,7 @@ __export(version_exports, {
31
31
  toReleasePrecisionVersion: () => toReleasePrecisionVersion
32
32
  });
33
33
  module.exports = __toCommonJS(version_exports);
34
- const LIBRARY_VERSION = "17.0.0-beta.26";
34
+ const LIBRARY_VERSION = "17.0.0-beta.27";
35
35
  const ADCP_VERSION = "3.3.0-beta.6";
36
36
  const ADCP_MAJOR_VERSION = 3;
37
37
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -109,10 +109,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
109
109
  "3.3-beta.6"
110
110
  ];
111
111
  const VERSION_INFO = {
112
- library: "17.0.0-beta.26",
112
+ library: "17.0.0-beta.27",
113
113
  adcp: "3.3.0-beta.6",
114
114
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
115
- generatedAt: "2026-11-14T15:52:16.390Z"
115
+ generatedAt: "2026-11-14T21:58:26.439Z"
116
116
  };
117
117
  function getAdcpVersion() {
118
118
  return ADCP_VERSION;
@@ -1,4 +1,4 @@
1
- const LIBRARY_VERSION = "17.0.0-beta.26";
1
+ const LIBRARY_VERSION = "17.0.0-beta.27";
2
2
  const ADCP_VERSION = "3.3.0-beta.6";
3
3
  const ADCP_MAJOR_VERSION = 3;
4
4
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -76,10 +76,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
76
76
  "3.3-beta.6"
77
77
  ];
78
78
  const VERSION_INFO = {
79
- library: "17.0.0-beta.26",
79
+ library: "17.0.0-beta.27",
80
80
  adcp: "3.3.0-beta.6",
81
81
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
82
- generatedAt: "2026-11-14T15:52:16.390Z"
82
+ generatedAt: "2026-11-14T21:58:26.439Z"
83
83
  };
84
84
  function getAdcpVersion() {
85
85
  return ADCP_VERSION;
@@ -1,7 +1,7 @@
1
1
  # AdCP Type Summary
2
2
 
3
3
  > Generated at: 2026-11-14
4
- > @adcp/sdk v17.0.0-beta.26
4
+ > @adcp/sdk v17.0.0-beta.27
5
5
 
6
6
  Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
7
7
 
package/docs/llms.txt CHANGED
@@ -1,7 +1,7 @@
1
1
  # Ad Context Protocol (AdCP)
2
2
 
3
3
  > Generated at: 2026-11-14
4
- > Library: @adcp/sdk v17.0.0-beta.26
4
+ > Library: @adcp/sdk v17.0.0-beta.27
5
5
  > AdCP major version: 3
6
6
  > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
7
7
  > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
16
16
 
17
17
  | Fact | Value |
18
18
  | --- | --- |
19
- | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.26` |
20
- | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.26 dist.integrity` |
19
+ | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.27` |
20
+ | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.27 dist.integrity` |
21
21
  | Node.js runtime | `^20.19.0 || >=22.12.0` |
22
22
  | Default AdCP wire release | `3.3.0-beta.6` |
23
23
  | Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.1.30`, `3.1.31`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.2.8`, `3.3.0-beta.6`, `3.3-beta.6` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
26
26
  For a checkout at the published release commit, install the exact package version:
27
27
 
28
28
  ```bash
29
- npm install --save-exact '@adcp/sdk@17.0.0-beta.26'
30
- npm view '@adcp/sdk@17.0.0-beta.26' dist.integrity
29
+ npm install --save-exact '@adcp/sdk@17.0.0-beta.27'
30
+ npm view '@adcp/sdk@17.0.0-beta.27' dist.integrity
31
31
  ```
32
32
 
33
33
  ### Required and optional peers
@@ -171,7 +171,13 @@ now sees a match. Pass the release you negotiated (for example `'3.2'`) to keep
171
171
  exact canonical-URL matching. At 3.3 every matching entry authorizes the
172
172
  agent, and its scope is the union of theirs: an exact entry and an origin-only
173
173
  entry for the same agent combine, so a narrower entry never removes scope
174
- another grants. `matched_entries` lists them all. Below 3.3, two exact matches
174
+ another grants. `matched_entries` lists them all. Their `signing_keys` combine
175
+ by the same reasoning, over the entries that also authorize the signed message's
176
+ scope: the agent is pinned only if every such entry pins, and may then sign with
177
+ any of their keys. The new
178
+ `resolvePublisherSigningKeyPin(adagents, agentUrl, { adcpVersion, country, propertyIds, at })`
179
+ applies that rule
180
+ ([adcp#9016](https://github.com/adcontextprotocol/adcp/issues/9016)). Below 3.3, two exact matches
175
181
  still fail closed as `ambiguous_agent_url`. `PropertyCrawler`
176
182
  uses each agent's served release, else its new `adcpVersion` option.
177
183
  Supply-path verification keeps exact matching under semantics version 1
@@ -92,6 +92,24 @@ successful fetch confirmed removal of the pin. A pinned key must also appear in
92
92
  the agent JWKS and match by RFC 7638 thumbprint. `kid`-only entries match nothing;
93
93
  revoked entries cannot authorize delivery. `key_origins` remains enforced.
94
94
 
95
+ Build `signingKeys` from the publisher's adagents.json with
96
+ `resolvePublisherSigningKeyPin(adagents, agentUrl, { adcpVersion, country, propertyIds, at })`,
97
+ passing the scope of the signed message. At AdCP 3.3 more than one
98
+ `authorized_agents[]` entry can match one agent, such as an origin-only entry
99
+ and the agent's full URL. Only entries that match the agent and authorize the
100
+ message's scope count. The publisher pins the agent only if every such entry
101
+ carries `signing_keys`, and the pin is then the union of their keys. One such
102
+ entry without `signing_keys` means no pin
103
+ ([adcp#9016](https://github.com/adcontextprotocol/adcp/issues/9016)). An entry
104
+ that authorizes nothing for the message never pins or unpins it. A message
105
+ about several properties gets one pin per property, and the key must satisfy
106
+ each.
107
+
108
+ The helper returns `undefined` for no pin, and `[]` (accept no key) when the
109
+ agent is not authorized for the message, so being unauthorized never reads as
110
+ unpinned. Use the same call in `refresh`, returning `null` when it gives
111
+ `undefined`.
112
+
95
113
  ## Governance
96
114
 
97
115
  Supply `buyerIdentity` for each authenticated request to governance verification
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adcp/sdk",
3
- "version": "17.0.0-beta.26",
3
+ "version": "17.0.0-beta.27",
4
4
  "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
5
5
  "workspaces": [
6
6
  ".",