@adcp/sdk 17.0.0-beta.26 → 17.0.0-beta.28

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 (68) hide show
  1. package/bin/adcp-storyboard-summary.js +47 -0
  2. package/bin/adcp.js +4 -0
  3. package/dist/lib/discovery/agent-directory.d.mts +10 -3
  4. package/dist/lib/discovery/agent-directory.d.ts +10 -3
  5. package/dist/lib/discovery/resolve-agent-properties.d.mts +94 -5
  6. package/dist/lib/discovery/resolve-agent-properties.d.ts +94 -5
  7. package/dist/lib/discovery/resolve-agent-properties.js +61 -0
  8. package/dist/lib/discovery/resolve-agent-properties.mjs +60 -0
  9. package/dist/lib/discovery/types.d.mts +14 -0
  10. package/dist/lib/discovery/types.d.ts +14 -0
  11. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  12. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  13. package/dist/lib/entrypoints/discovery.js +2 -0
  14. package/dist/lib/entrypoints/discovery.mjs +3 -1
  15. package/dist/lib/index.d.mts +1 -1
  16. package/dist/lib/index.d.ts +1 -1
  17. package/dist/lib/index.js +2 -0
  18. package/dist/lib/index.mjs +3 -1
  19. package/dist/lib/registry/types.generated.d.ts +8 -6
  20. package/dist/lib/testing/compliance/comply.d.mts +16 -1
  21. package/dist/lib/testing/compliance/comply.d.ts +16 -1
  22. package/dist/lib/testing/compliance/comply.js +77 -6
  23. package/dist/lib/testing/compliance/comply.mjs +83 -7
  24. package/dist/lib/testing/compliance/index.d.mts +1 -1
  25. package/dist/lib/testing/compliance/index.d.ts +1 -1
  26. package/dist/lib/testing/compliance/storyboard-tracks.d.mts +6 -0
  27. package/dist/lib/testing/compliance/storyboard-tracks.d.ts +6 -0
  28. package/dist/lib/testing/compliance/storyboard-tracks.js +26 -4
  29. package/dist/lib/testing/compliance/storyboard-tracks.mjs +24 -3
  30. package/dist/lib/testing/compliance/summary.d.mts +3 -1
  31. package/dist/lib/testing/compliance/summary.d.ts +3 -1
  32. package/dist/lib/testing/compliance/summary.js +2 -1
  33. package/dist/lib/testing/compliance/summary.mjs +2 -1
  34. package/dist/lib/testing/compliance/types.d.mts +30 -1
  35. package/dist/lib/testing/compliance/types.d.ts +30 -1
  36. package/dist/lib/testing/index.d.mts +1 -1
  37. package/dist/lib/testing/index.d.ts +1 -1
  38. package/dist/lib/testing/index.js +4 -0
  39. package/dist/lib/testing/index.mjs +4 -0
  40. package/dist/lib/testing/storyboard/index.d.mts +4 -2
  41. package/dist/lib/testing/storyboard/index.d.ts +4 -2
  42. package/dist/lib/testing/storyboard/index.js +7 -0
  43. package/dist/lib/testing/storyboard/index.mjs +6 -1
  44. package/dist/lib/testing/storyboard/runner.d.mts +7 -0
  45. package/dist/lib/testing/storyboard/runner.d.ts +7 -0
  46. package/dist/lib/testing/storyboard/runner.js +15 -0
  47. package/dist/lib/testing/storyboard/runner.mjs +14 -0
  48. package/dist/lib/testing/storyboard/types.d.mts +77 -0
  49. package/dist/lib/testing/storyboard/types.d.ts +77 -0
  50. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  51. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  52. package/dist/lib/testing/storyboard/verdict-explanation.d.mts +47 -0
  53. package/dist/lib/testing/storyboard/verdict-explanation.d.ts +47 -0
  54. package/dist/lib/testing/storyboard/verdict-explanation.js +309 -0
  55. package/dist/lib/testing/storyboard/verdict-explanation.mjs +283 -0
  56. package/dist/lib/testing/types.d.mts +11 -1
  57. package/dist/lib/testing/types.d.ts +11 -1
  58. package/dist/lib/version.d.mts +3 -3
  59. package/dist/lib/version.d.ts +3 -3
  60. package/dist/lib/version.js +3 -3
  61. package/dist/lib/version.mjs +3 -3
  62. package/docs/TYPE-SUMMARY.md +2 -2
  63. package/docs/guides/VALIDATE-YOUR-AGENT.md +28 -0
  64. package/docs/llms.txt +2 -2
  65. package/docs/migration-14.x-rc-worksheet.md +4 -4
  66. package/docs/migration-16-to-17.md +7 -1
  67. package/docs/migration-agent-resolution-3.3.md +18 -0
  68. package/package.json +1 -1
@@ -147,9 +147,55 @@ function buildStoryboardSummaryMarkdown(results, agentUrl, overallPassed) {
147
147
  }
148
148
  lines.push('');
149
149
  }
150
+ // Failing storyboards no failed step explains (adcp#8576).
151
+ const storyboardLevel = results.filter(
152
+ r => r.overall_passed === false && r.verdict_detail && !failures.some(f => f.storyboard === (r.storyboard_id || ''))
153
+ );
154
+ if (storyboardLevel.length > 0) {
155
+ lines.push('## Storyboard-level verdicts');
156
+ lines.push('');
157
+ lines.push('| Storyboard | Reason | Detail |');
158
+ lines.push('|---|---|---|');
159
+ for (const r of storyboardLevel) {
160
+ lines.push(
161
+ `| ${escapeMarkdownCell(r.storyboard_id || '')} | ${escapeMarkdownCell(r.verdict_reason || 'unexplained')} | ${escapeMarkdownCell(r.verdict_detail)} |`
162
+ );
163
+ }
164
+ lines.push('');
165
+ }
150
166
  return lines.join('\n');
151
167
  }
152
168
 
169
+ const VERDICT_CONTRIBUTOR_LIMIT = 8;
170
+
171
+ /**
172
+ * Console lines explaining a failing storyboard verdict (adcp#8576): the
173
+ * runner's `verdict_reason`, `verdict_detail`, and the contributing steps,
174
+ * assertions and phases. Empty for a passing result or one from a runner
175
+ * that predates the fields. Every runner- or agent-sourced string is
176
+ * terminal-escaped.
177
+ */
178
+ function formatStoryboardVerdictLines(result, indent = ' ') {
179
+ if (!result || result.overall_passed !== false || !result.verdict_reason) return [];
180
+ const lines = [
181
+ `${indent}Why: [${escapeTerminalControlChars(result.verdict_reason)}] ${escapeTerminalControlChars(result.verdict_detail ?? '')}`,
182
+ ];
183
+ const rows = Array.isArray(result.verdict_contributing) ? result.verdict_contributing : [];
184
+ for (const row of rows.slice(0, VERDICT_CONTRIBUTOR_LIMIT)) {
185
+ const where = [row.phase_id && `phase ${row.phase_id}`, row.pass_index !== undefined && `pass ${row.pass_index}`]
186
+ .filter(Boolean)
187
+ .join(', ');
188
+ const skip = row.skip_reason ? ` ${row.skip_reason}${row.requirement ? `:${row.requirement}` : ''}` : '';
189
+ const head = `${row.kind} ${row.id} ${row.status}${skip}${where ? ` (${where})` : ''}`;
190
+ const message = row.message ? ` — ${row.message}` : '';
191
+ lines.push(`${indent} - ${escapeTerminalControlChars(head + message)}`);
192
+ }
193
+ if (rows.length > VERDICT_CONTRIBUTOR_LIMIT) {
194
+ lines.push(`${indent} … ${rows.length - VERDICT_CONTRIBUTOR_LIMIT} more (use --json for all)`);
195
+ }
196
+ return lines;
197
+ }
198
+
153
199
  /**
154
200
  * Writes `content` to `summaryFile`. Failures are downgraded to a stderr
155
201
  * warning rather than exiting the process — the markdown summary is a
@@ -474,6 +520,7 @@ module.exports = {
474
520
  formatJwtExpClaim,
475
521
  formatStepSkipLines,
476
522
  formatStepVerdictLines,
523
+ formatStoryboardVerdictLines,
477
524
  isCoverageGapRow,
478
525
  isCoverageUnavailableStep,
479
526
  unverifiedSigningCoverage,
package/bin/adcp.js CHANGED
@@ -52,6 +52,7 @@ const {
52
52
  formatJwtExpClaim,
53
53
  formatStepSkipLines,
54
54
  formatStepVerdictLines,
55
+ formatStoryboardVerdictLines,
55
56
  isCoverageUnavailableStep,
56
57
  unverifiedSigningCoverage,
57
58
  parseRequestSigningFlags,
@@ -3158,6 +3159,8 @@ async function handleStoryboardRun(args) {
3158
3159
  console.log(
3159
3160
  `${overallIcon} ${result.passed_count} passed, ${result.failed_count} failed, ${result.skipped_count} skipped (${result.total_duration_ms}ms)${hintTail}`
3160
3161
  );
3162
+ // A storyboard can fail with every visible step green; say why (adcp#8576).
3163
+ for (const line of formatStoryboardVerdictLines(result)) console.log(line);
3161
3164
  printStrictSummary(result.strict_validation_summary);
3162
3165
  printNotices(result.notices);
3163
3166
  }
@@ -4164,6 +4167,7 @@ async function handleLocalAgentStoryboardRun(modulePath, args, opts) {
4164
4167
  console.log(
4165
4168
  `${icon} ${sb.storyboard_title} (${sb.storyboard_id}) — ${sb.passed_count} passed, ${sb.failed_count} failed, ${sb.skipped_count} skipped`
4166
4169
  );
4170
+ for (const line of formatStoryboardVerdictLines(sb)) console.log(line);
4167
4171
  }
4168
4172
  if (result.not_applicable.length > 0) {
4169
4173
  console.log(`\n${result.not_applicable.length} storyboard(s) not applicable (out of scope):`);
@@ -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';