@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.23

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 (223) hide show
  1. package/README.md +26 -2
  2. package/dist/lib/adapters/version/index.d.mts +1 -1
  3. package/dist/lib/adapters/version/index.d.ts +1 -1
  4. package/dist/lib/adapters/version/index.js +2 -0
  5. package/dist/lib/adapters/version/index.mjs +2 -0
  6. package/dist/lib/adapters/version/negotiate.d.mts +13 -0
  7. package/dist/lib/adapters/version/negotiate.d.ts +13 -0
  8. package/dist/lib/adapters/version/negotiate.js +6 -0
  9. package/dist/lib/adapters/version/negotiate.mjs +5 -0
  10. package/dist/lib/client/core.d.mts +4 -0
  11. package/dist/lib/client/core.d.ts +4 -0
  12. package/dist/lib/client/core.js +13 -0
  13. package/dist/lib/client/core.mjs +12 -0
  14. package/dist/lib/conformance/property-lists.d.mts +1 -1
  15. package/dist/lib/conformance/property-lists.d.ts +1 -1
  16. package/dist/lib/conformance/property-lists.js +1 -1
  17. package/dist/lib/conformance/property-lists.mjs +1 -1
  18. package/dist/lib/core/SingleAgentClient.d.mts +23 -1
  19. package/dist/lib/core/SingleAgentClient.d.ts +23 -1
  20. package/dist/lib/core/SingleAgentClient.js +102 -18
  21. package/dist/lib/core/SingleAgentClient.mjs +108 -18
  22. package/dist/lib/core/targeting-helpers.d.mts +123 -0
  23. package/dist/lib/core/targeting-helpers.d.ts +123 -0
  24. package/dist/lib/core/targeting-helpers.js +412 -0
  25. package/dist/lib/core/targeting-helpers.mjs +370 -0
  26. package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
  27. package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
  28. package/dist/lib/entrypoints/client-account-changes.js +28 -0
  29. package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
  30. package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
  31. package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
  32. package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
  33. package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
  34. package/dist/lib/entrypoints/discovery.d.mts +9 -0
  35. package/dist/lib/entrypoints/discovery.d.ts +9 -0
  36. package/dist/lib/entrypoints/discovery.js +72 -0
  37. package/dist/lib/entrypoints/discovery.mjs +56 -0
  38. package/dist/lib/entrypoints/errors.d.mts +11 -0
  39. package/dist/lib/entrypoints/errors.d.ts +11 -0
  40. package/dist/lib/entrypoints/errors.js +159 -0
  41. package/dist/lib/entrypoints/errors.mjs +132 -0
  42. package/dist/lib/entrypoints/media-buy.d.mts +5 -0
  43. package/dist/lib/entrypoints/media-buy.d.ts +5 -0
  44. package/dist/lib/entrypoints/media-buy.js +119 -0
  45. package/dist/lib/entrypoints/media-buy.mjs +100 -0
  46. package/dist/lib/entrypoints/registry.d.mts +5 -0
  47. package/dist/lib/entrypoints/registry.d.ts +5 -0
  48. package/dist/lib/entrypoints/registry.js +61 -0
  49. package/dist/lib/entrypoints/registry.mjs +40 -0
  50. package/dist/lib/entrypoints/utils.d.mts +7 -0
  51. package/dist/lib/entrypoints/utils.d.ts +7 -0
  52. package/dist/lib/entrypoints/utils.js +100 -0
  53. package/dist/lib/entrypoints/utils.mjs +72 -0
  54. package/dist/lib/entrypoints/version.d.mts +3 -0
  55. package/dist/lib/entrypoints/version.d.ts +3 -0
  56. package/dist/lib/entrypoints/version.js +57 -0
  57. package/dist/lib/entrypoints/version.mjs +36 -0
  58. package/dist/lib/index.d.mts +1 -1
  59. package/dist/lib/index.d.ts +1 -1
  60. package/dist/lib/media-buy/action-contracts.js +3 -3
  61. package/dist/lib/media-buy/action-contracts.mjs +1 -1
  62. package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
  63. package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
  64. package/dist/lib/media-buy/creative-start-policy.js +59 -0
  65. package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
  66. package/dist/lib/media-buy/valid-actions.d.mts +47 -0
  67. package/dist/lib/media-buy/valid-actions.d.ts +47 -0
  68. package/dist/lib/media-buy/valid-actions.js +42 -0
  69. package/dist/lib/media-buy/valid-actions.mjs +18 -0
  70. package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
  71. package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
  72. package/dist/lib/net/pin-and-bind-fetch.js +209 -0
  73. package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
  74. package/dist/lib/protocols/mcp-modern.js +20 -4
  75. package/dist/lib/protocols/mcp-modern.mjs +20 -4
  76. package/dist/lib/registry/types.generated.d.ts +224 -3
  77. package/dist/lib/reporting/ledger/index.d.mts +1 -0
  78. package/dist/lib/reporting/ledger/index.d.ts +1 -0
  79. package/dist/lib/reporting/ledger/index.js +3 -1
  80. package/dist/lib/reporting/ledger/index.mjs +1 -0
  81. package/dist/lib/reporting/ledger/instant.d.mts +5 -0
  82. package/dist/lib/reporting/ledger/instant.d.ts +5 -0
  83. package/dist/lib/reporting/ledger/instant.js +10 -0
  84. package/dist/lib/reporting/ledger/instant.mjs +9 -0
  85. package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
  86. package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
  87. package/dist/lib/reporting/ledger/issue-events.js +310 -0
  88. package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
  89. package/dist/lib/reporting/service/index.d.mts +36 -1
  90. package/dist/lib/reporting/service/index.d.ts +36 -1
  91. package/dist/lib/reporting/service/index.js +51 -1
  92. package/dist/lib/reporting/service/index.mjs +52 -2
  93. package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
  94. package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
  95. package/dist/lib/reporting/service/scheduler-support.js +1 -1
  96. package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
  97. package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
  98. package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
  99. package/dist/lib/server/capabilities-release-projection.js +128 -0
  100. package/dist/lib/server/capabilities-release-projection.mjs +112 -0
  101. package/dist/lib/server/create-adcp-server.d.mts +29 -5
  102. package/dist/lib/server/create-adcp-server.d.ts +29 -5
  103. package/dist/lib/server/create-adcp-server.js +97 -24
  104. package/dist/lib/server/create-adcp-server.mjs +108 -23
  105. package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
  106. package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
  107. package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
  108. package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
  109. package/dist/lib/server/declared-input-schema.d.mts +108 -0
  110. package/dist/lib/server/declared-input-schema.d.ts +108 -0
  111. package/dist/lib/server/declared-input-schema.js +167 -0
  112. package/dist/lib/server/declared-input-schema.mjs +137 -0
  113. package/dist/lib/server/envelope-allowlist.d.mts +1 -105
  114. package/dist/lib/server/envelope-allowlist.d.ts +1 -105
  115. package/dist/lib/server/envelope-allowlist.js +3 -79
  116. package/dist/lib/server/envelope-allowlist.mjs +1 -71
  117. package/dist/lib/server/errors.d.mts +1 -186
  118. package/dist/lib/server/errors.d.ts +1 -186
  119. package/dist/lib/server/errors.js +3 -98
  120. package/dist/lib/server/errors.mjs +1 -94
  121. package/dist/lib/server/index.d.mts +1 -1
  122. package/dist/lib/server/index.d.ts +1 -1
  123. package/dist/lib/server/mcp-modern-server.js +21 -4
  124. package/dist/lib/server/mcp-modern-server.mjs +21 -4
  125. package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
  126. package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
  127. package/dist/lib/server/media-buy-action-resolver.js +10 -1
  128. package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
  129. package/dist/lib/server/media-buy-helpers.d.mts +1 -47
  130. package/dist/lib/server/media-buy-helpers.d.ts +1 -47
  131. package/dist/lib/server/media-buy-helpers.js +3 -23
  132. package/dist/lib/server/media-buy-helpers.mjs +1 -18
  133. package/dist/lib/server/pick-safe-details.d.mts +1 -89
  134. package/dist/lib/server/pick-safe-details.d.ts +1 -89
  135. package/dist/lib/server/pick-safe-details.js +3 -61
  136. package/dist/lib/server/pick-safe-details.mjs +1 -56
  137. package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
  138. package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
  139. package/dist/lib/server/pin-and-bind-fetch.js +3 -190
  140. package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
  141. package/dist/lib/server/targeting-helpers.d.mts +1 -123
  142. package/dist/lib/server/targeting-helpers.d.ts +1 -123
  143. package/dist/lib/server/targeting-helpers.js +3 -393
  144. package/dist/lib/server/targeting-helpers.mjs +1 -370
  145. package/dist/lib/server/test-controller.js +7 -3
  146. package/dist/lib/server/test-controller.mjs +7 -3
  147. package/dist/lib/storage/memory-ledger.js +219 -1
  148. package/dist/lib/storage/memory-ledger.mjs +223 -1
  149. package/dist/lib/testing/client.js +26 -5
  150. package/dist/lib/testing/client.mjs +24 -5
  151. package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
  152. package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
  153. package/dist/lib/testing/comply-controller.js +7 -2
  154. package/dist/lib/testing/comply-controller.mjs +7 -2
  155. package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
  156. package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
  157. package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
  158. package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
  159. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
  160. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
  161. package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
  162. package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
  163. package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
  164. package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
  165. package/dist/lib/testing/storyboard/runner.js +4 -4
  166. package/dist/lib/testing/storyboard/runner.mjs +4 -4
  167. package/dist/lib/testing/storyboard/task-map.js +4 -1
  168. package/dist/lib/testing/storyboard/task-map.mjs +4 -1
  169. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  170. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  171. package/dist/lib/utils/adcp-error-response.d.mts +196 -0
  172. package/dist/lib/utils/adcp-error-response.d.ts +196 -0
  173. package/dist/lib/utils/adcp-error-response.js +118 -0
  174. package/dist/lib/utils/adcp-error-response.mjs +95 -0
  175. package/dist/lib/utils/buyer-retry-policy.js +2 -2
  176. package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
  177. package/dist/lib/utils/capabilities.d.mts +6 -0
  178. package/dist/lib/utils/capabilities.d.ts +6 -0
  179. package/dist/lib/utils/capabilities.js +6 -2
  180. package/dist/lib/utils/capabilities.mjs +6 -2
  181. package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
  182. package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
  183. package/dist/lib/utils/envelope-allowlist.js +98 -0
  184. package/dist/lib/utils/envelope-allowlist.mjs +71 -0
  185. package/dist/lib/utils/pick-safe-details.d.mts +89 -0
  186. package/dist/lib/utils/pick-safe-details.d.ts +89 -0
  187. package/dist/lib/utils/pick-safe-details.js +80 -0
  188. package/dist/lib/utils/pick-safe-details.mjs +56 -0
  189. package/dist/lib/v2/projection/augment-response.d.mts +4 -0
  190. package/dist/lib/v2/projection/augment-response.d.ts +4 -0
  191. package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
  192. package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
  193. package/dist/lib/v2/projection/creative-delivery.js +20 -4
  194. package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
  195. package/dist/lib/v2/projection/index.d.mts +2 -2
  196. package/dist/lib/v2/projection/index.d.ts +2 -2
  197. package/dist/lib/v2/projection/index.js +4 -0
  198. package/dist/lib/v2/projection/index.mjs +5 -1
  199. package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
  200. package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
  201. package/dist/lib/v2/projection/legacy-metadata.js +14 -0
  202. package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
  203. package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
  204. package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
  205. package/dist/lib/v2/projection/legacy-routes.js +2 -1
  206. package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
  207. package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
  208. package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
  209. package/dist/lib/v2/projection/v1-to-v2.js +18 -11
  210. package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
  211. package/dist/lib/version.d.mts +3 -3
  212. package/dist/lib/version.d.ts +3 -3
  213. package/dist/lib/version.js +3 -3
  214. package/dist/lib/version.mjs +3 -3
  215. package/docs/TYPE-SUMMARY.md +2 -2
  216. package/docs/guides/CREATIVE-DELIVERY.md +12 -0
  217. package/docs/guides/REPORTING-LEDGER.md +121 -0
  218. package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
  219. package/docs/llms.txt +2 -2
  220. package/docs/migration-14.x-rc-worksheet.md +4 -4
  221. package/docs/migration-16-to-17.md +149 -0
  222. package/docs/migration-reporting-storage-package.md +10 -0
  223. package/package.json +106 -1
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Media buy response helpers that eliminate common implementation traps.
3
+ *
4
+ * These helpers encode protocol rules (status→valid_actions mapping,
5
+ * required cancellation metadata, initial revision numbers) so agent
6
+ * builders get the right shape by default.
7
+ */
8
+ import type { MediaBuyStatus, CanceledBy, Package } from '../types/core.generated';
9
+ import type { CreateMediaBuySuccess } from '../types/tools.generated';
10
+ /**
11
+ * Actions a buyer can perform on a media buy.
12
+ * Derived from the generated schema to stay in sync automatically.
13
+ */
14
+ export type ValidAction = NonNullable<CreateMediaBuySuccess['valid_actions']>[number];
15
+ /**
16
+ * Returns the default set of valid buyer actions for a given media buy status.
17
+ *
18
+ * Terminal statuses (completed, rejected, canceled) return an empty array.
19
+ * Active statuses return the full set of actions; paused restricts to
20
+ * resume, cancel, and budget/date updates.
21
+ *
22
+ * Both pending statuses allow full modification — the protocol permits
23
+ * restructuring a buy (packages, budget, dates) while awaiting creatives
24
+ * or start date.
25
+ *
26
+ * Sellers with restricted capabilities can filter the result:
27
+ * ```typescript
28
+ * const actions = validActionsForStatus('active')
29
+ * .filter(a => a !== 'sync_creatives'); // no creative management
30
+ * ```
31
+ */
32
+ export declare function validActionsForStatus(status: MediaBuyStatus): ValidAction[];
33
+ /**
34
+ * Input for cancelMediaBuyResponse(). Requires the fields that agent builders
35
+ * commonly forget — canceled_by and revision are mandatory,
36
+ * canceled_at defaults to now.
37
+ */
38
+ export interface CancelMediaBuyInput {
39
+ media_buy_id: string;
40
+ canceled_by: CanceledBy;
41
+ /** Current revision after the cancellation update. */
42
+ revision: number;
43
+ reason?: string;
44
+ canceled_at?: string;
45
+ affected_packages?: Package[];
46
+ sandbox?: boolean;
47
+ }
@@ -0,0 +1,42 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+ var valid_actions_exports = {};
20
+ __export(valid_actions_exports, {
21
+ validActionsForStatus: () => validActionsForStatus
22
+ });
23
+ module.exports = __toCommonJS(valid_actions_exports);
24
+ function validActionsForStatus(status) {
25
+ switch (status) {
26
+ case "pending_creatives":
27
+ case "pending_start":
28
+ return ["cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
29
+ case "active":
30
+ return ["pause", "cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
31
+ case "paused":
32
+ return ["resume", "cancel", "update_budget", "update_dates"];
33
+ case "completed":
34
+ case "rejected":
35
+ case "canceled":
36
+ return [];
37
+ }
38
+ }
39
+ // Annotate the CommonJS export names for ESM import in node:
40
+ 0 && (module.exports = {
41
+ validActionsForStatus
42
+ });
@@ -0,0 +1,18 @@
1
+ function validActionsForStatus(status) {
2
+ switch (status) {
3
+ case "pending_creatives":
4
+ case "pending_start":
5
+ return ["cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
6
+ case "active":
7
+ return ["pause", "cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
8
+ case "paused":
9
+ return ["resume", "cancel", "update_budget", "update_dates"];
10
+ case "completed":
11
+ case "rejected":
12
+ case "canceled":
13
+ return [];
14
+ }
15
+ }
16
+ export {
17
+ validActionsForStatus
18
+ };
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Pin-and-bind fetch — DNS-rebinding-resistant `fetch` for outbound webhook
3
+ * delivery and other callbacks where the destination is buyer-supplied.
4
+ *
5
+ * The problem: validating a `push_notification_config.url`'s LITERAL hostname
6
+ * against an SSRF deny list does not protect against a DNS-rebinding attack.
7
+ * A buyer can register `https://rebind.attacker.com/`, pass the literal-host
8
+ * check, and then flip the A-record TTL to `169.254.169.254` (cloud metadata)
9
+ * or `127.0.0.1` (loopback) before the webhook fires. Node's `fetch` resolves
10
+ * the host fresh at request time, gets the rebound IP, and posts the
11
+ * signed payload to the attacker-controlled destination.
12
+ *
13
+ * The fix: control DNS resolution and connect-target inside the fetch itself.
14
+ * 1. Resolve the hostname.
15
+ * 2. Validate every resolved IP against the SSRF policy (CIDR deny lists,
16
+ * metadata-host names, scheme rules).
17
+ * 3. Pin the connection to the validated IP — undici opens TCP/TLS to that
18
+ * specific address, but the original hostname is preserved for TLS SNI
19
+ * and the `Host:` header so HTTPS routing still works.
20
+ * 4. Never follow redirects. Steps 1-3 only ever see the URL the caller
21
+ * passed, so a followed `Location:` hop would bypass all of them.
22
+ *
23
+ * Implementation note: undici's `Agent` accepts a `connect.lookup` callback
24
+ * with the same signature as `dns.lookup`. We hook the callback, resolve via
25
+ * `dns.lookup({ all: true })` to see EVERY address the host can reach, run
26
+ * the resolved IPs through {@link enforceSsrfPolicyResolved}, and only return
27
+ * a pinned address when every resolved IP is in an allowed range. This
28
+ * matches the AdCP substitution-observer SSRF contract — a host that
29
+ * resolves to *any* denied IP is treated as suspect and rejected wholesale.
30
+ */
31
+ import { Agent } from 'undici';
32
+ import { type LookupAddress } from 'node:dns';
33
+ import type { SsrfPolicy } from '../substitution/types.mjs';
34
+ /**
35
+ * Default SSRF policy for outbound webhook delivery. Differs from
36
+ * `DEFAULT_SSRF_POLICY` (substitution observer) only in that it allows
37
+ * `host_literal_policy: 'allow'` — webhook URLs MAY use IP literals
38
+ * (e.g. `https://203.0.113.10/cb`) as long as the IP is allowed by both
39
+ * the contract CIDRs and the SDK's shared private-address classifier.
40
+ * Schemes are restricted to https; signed webhooks SHOULD be delivered
41
+ * over TLS.
42
+ *
43
+ * For storyboard / in-process tests where the receiver runs on
44
+ * `http://127.0.0.1:port`, use {@link LOOPBACK_OK_WEBHOOK_SSRF_POLICY}
45
+ * instead. That preset relaxes only the loopback + http rules and keeps
46
+ * every other deny range — adopters get most of the SSRF protection
47
+ * during tests without disabling pin-and-bind entirely.
48
+ */
49
+ export declare const WEBHOOK_SSRF_POLICY: SsrfPolicy;
50
+ /**
51
+ * Pin-and-bind policy that allows http URLs and IPv4/IPv6 loopback so
52
+ * adopters can enable pin-and-bind for production webhook delivery while
53
+ * keeping storyboard / in-process tests working — `createWebhookReceiver`
54
+ * listens on `http://127.0.0.1:port`. Every other private CIDR, metadata
55
+ * host, and shared private range is still denied, so native IPv4/IPv6
56
+ * loopback is the only address relaxation. Pass to
57
+ * `createPinAndBindFetch({ policy })` from your test fixture or storyboard
58
+ * runner harness; do NOT use in production.
59
+ */
60
+ export declare const LOOPBACK_OK_WEBHOOK_SSRF_POLICY: SsrfPolicy;
61
+ /**
62
+ * Signature of the lookup callback `dns.lookup` accepts. Re-declared here
63
+ * because the native type from `node:dns` is a complex overload set; the
64
+ * shape we actually need is the all=true variant the Agent expects.
65
+ */
66
+ export type DnsLookupAll = (hostname: string, options: {
67
+ family?: number;
68
+ hints?: number;
69
+ all: true;
70
+ verbatim?: boolean;
71
+ }, callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void) => void;
72
+ export interface PinAndBindFetchOptions {
73
+ /**
74
+ * SSRF policy to enforce against resolved IPs. Defaults to
75
+ * {@link WEBHOOK_SSRF_POLICY} (https-only, all private/loopback/metadata
76
+ * ranges denied, IP literals allowed). The built-in strict and loopback
77
+ * presets inherit the SDK's full shared private-address classification;
78
+ * custom policies own their private ranges. Cloud metadata, link-local, and
79
+ * opaque translation/tunnel targets in the shared always-blocked tier can
80
+ * never be enabled by a policy override.
81
+ */
82
+ policy?: SsrfPolicy;
83
+ /**
84
+ * Override the underlying DNS lookup. Default uses `dns.lookup` with
85
+ * `all: true`. Tests inject a stub to simulate rebinding attacks without
86
+ * touching real DNS.
87
+ */
88
+ lookup?: DnsLookupAll;
89
+ /**
90
+ * Forward to `Agent` — connect-attempt timeout, TLS options, etc. Cannot
91
+ * override `lookup`; that is wired by this helper.
92
+ */
93
+ agentOptions?: Omit<Agent.Options, 'connect'> & {
94
+ connect?: Omit<NonNullable<Agent.Options['connect']>, 'lookup'>;
95
+ };
96
+ }
97
+ /**
98
+ * Build a `fetch` that pins outbound connections to the IPs the SSRF policy
99
+ * allows, defeating DNS-rebinding attacks against per-attempt DNS resolution.
100
+ *
101
+ * This is the default `fetch` for `createWebhookEmitter` /
102
+ * `createAdcpServer({ webhooks })`, so production webhook delivery is
103
+ * rebinding-protected without extra wiring. Call it explicitly only to
104
+ * override the policy — e.g. {@link LOOPBACK_OK_WEBHOOK_SSRF_POLICY} for
105
+ * storyboard tests that deliver to a loopback http receiver. See
106
+ * `docs/guides/SIGNING-GUIDE.md` § Webhook SSRF defense.
107
+ *
108
+ * Construct once per emitter and reuse — each call instantiates a fresh
109
+ * `undici.Agent` with its own connection pool.
110
+ *
111
+ * @example
112
+ * ```ts
113
+ * import { createWebhookEmitter, createPinAndBindFetch } from '@adcp/sdk/server';
114
+ *
115
+ * const emitter = createWebhookEmitter({
116
+ * signerKey: webhookKey,
117
+ * fetch: createPinAndBindFetch(),
118
+ * });
119
+ * ```
120
+ */
121
+ export declare function createPinAndBindFetch(options?: PinAndBindFetchOptions): typeof fetch;
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Pin-and-bind fetch — DNS-rebinding-resistant `fetch` for outbound webhook
3
+ * delivery and other callbacks where the destination is buyer-supplied.
4
+ *
5
+ * The problem: validating a `push_notification_config.url`'s LITERAL hostname
6
+ * against an SSRF deny list does not protect against a DNS-rebinding attack.
7
+ * A buyer can register `https://rebind.attacker.com/`, pass the literal-host
8
+ * check, and then flip the A-record TTL to `169.254.169.254` (cloud metadata)
9
+ * or `127.0.0.1` (loopback) before the webhook fires. Node's `fetch` resolves
10
+ * the host fresh at request time, gets the rebound IP, and posts the
11
+ * signed payload to the attacker-controlled destination.
12
+ *
13
+ * The fix: control DNS resolution and connect-target inside the fetch itself.
14
+ * 1. Resolve the hostname.
15
+ * 2. Validate every resolved IP against the SSRF policy (CIDR deny lists,
16
+ * metadata-host names, scheme rules).
17
+ * 3. Pin the connection to the validated IP — undici opens TCP/TLS to that
18
+ * specific address, but the original hostname is preserved for TLS SNI
19
+ * and the `Host:` header so HTTPS routing still works.
20
+ * 4. Never follow redirects. Steps 1-3 only ever see the URL the caller
21
+ * passed, so a followed `Location:` hop would bypass all of them.
22
+ *
23
+ * Implementation note: undici's `Agent` accepts a `connect.lookup` callback
24
+ * with the same signature as `dns.lookup`. We hook the callback, resolve via
25
+ * `dns.lookup({ all: true })` to see EVERY address the host can reach, run
26
+ * the resolved IPs through {@link enforceSsrfPolicyResolved}, and only return
27
+ * a pinned address when every resolved IP is in an allowed range. This
28
+ * matches the AdCP substitution-observer SSRF contract — a host that
29
+ * resolves to *any* denied IP is treated as suspect and rejected wholesale.
30
+ */
31
+ import { Agent } from 'undici';
32
+ import { type LookupAddress } from 'node:dns';
33
+ import type { SsrfPolicy } from '../substitution/types';
34
+ /**
35
+ * Default SSRF policy for outbound webhook delivery. Differs from
36
+ * `DEFAULT_SSRF_POLICY` (substitution observer) only in that it allows
37
+ * `host_literal_policy: 'allow'` — webhook URLs MAY use IP literals
38
+ * (e.g. `https://203.0.113.10/cb`) as long as the IP is allowed by both
39
+ * the contract CIDRs and the SDK's shared private-address classifier.
40
+ * Schemes are restricted to https; signed webhooks SHOULD be delivered
41
+ * over TLS.
42
+ *
43
+ * For storyboard / in-process tests where the receiver runs on
44
+ * `http://127.0.0.1:port`, use {@link LOOPBACK_OK_WEBHOOK_SSRF_POLICY}
45
+ * instead. That preset relaxes only the loopback + http rules and keeps
46
+ * every other deny range — adopters get most of the SSRF protection
47
+ * during tests without disabling pin-and-bind entirely.
48
+ */
49
+ export declare const WEBHOOK_SSRF_POLICY: SsrfPolicy;
50
+ /**
51
+ * Pin-and-bind policy that allows http URLs and IPv4/IPv6 loopback so
52
+ * adopters can enable pin-and-bind for production webhook delivery while
53
+ * keeping storyboard / in-process tests working — `createWebhookReceiver`
54
+ * listens on `http://127.0.0.1:port`. Every other private CIDR, metadata
55
+ * host, and shared private range is still denied, so native IPv4/IPv6
56
+ * loopback is the only address relaxation. Pass to
57
+ * `createPinAndBindFetch({ policy })` from your test fixture or storyboard
58
+ * runner harness; do NOT use in production.
59
+ */
60
+ export declare const LOOPBACK_OK_WEBHOOK_SSRF_POLICY: SsrfPolicy;
61
+ /**
62
+ * Signature of the lookup callback `dns.lookup` accepts. Re-declared here
63
+ * because the native type from `node:dns` is a complex overload set; the
64
+ * shape we actually need is the all=true variant the Agent expects.
65
+ */
66
+ export type DnsLookupAll = (hostname: string, options: {
67
+ family?: number;
68
+ hints?: number;
69
+ all: true;
70
+ verbatim?: boolean;
71
+ }, callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void) => void;
72
+ export interface PinAndBindFetchOptions {
73
+ /**
74
+ * SSRF policy to enforce against resolved IPs. Defaults to
75
+ * {@link WEBHOOK_SSRF_POLICY} (https-only, all private/loopback/metadata
76
+ * ranges denied, IP literals allowed). The built-in strict and loopback
77
+ * presets inherit the SDK's full shared private-address classification;
78
+ * custom policies own their private ranges. Cloud metadata, link-local, and
79
+ * opaque translation/tunnel targets in the shared always-blocked tier can
80
+ * never be enabled by a policy override.
81
+ */
82
+ policy?: SsrfPolicy;
83
+ /**
84
+ * Override the underlying DNS lookup. Default uses `dns.lookup` with
85
+ * `all: true`. Tests inject a stub to simulate rebinding attacks without
86
+ * touching real DNS.
87
+ */
88
+ lookup?: DnsLookupAll;
89
+ /**
90
+ * Forward to `Agent` — connect-attempt timeout, TLS options, etc. Cannot
91
+ * override `lookup`; that is wired by this helper.
92
+ */
93
+ agentOptions?: Omit<Agent.Options, 'connect'> & {
94
+ connect?: Omit<NonNullable<Agent.Options['connect']>, 'lookup'>;
95
+ };
96
+ }
97
+ /**
98
+ * Build a `fetch` that pins outbound connections to the IPs the SSRF policy
99
+ * allows, defeating DNS-rebinding attacks against per-attempt DNS resolution.
100
+ *
101
+ * This is the default `fetch` for `createWebhookEmitter` /
102
+ * `createAdcpServer({ webhooks })`, so production webhook delivery is
103
+ * rebinding-protected without extra wiring. Call it explicitly only to
104
+ * override the policy — e.g. {@link LOOPBACK_OK_WEBHOOK_SSRF_POLICY} for
105
+ * storyboard tests that deliver to a loopback http receiver. See
106
+ * `docs/guides/SIGNING-GUIDE.md` § Webhook SSRF defense.
107
+ *
108
+ * Construct once per emitter and reuse — each call instantiates a fresh
109
+ * `undici.Agent` with its own connection pool.
110
+ *
111
+ * @example
112
+ * ```ts
113
+ * import { createWebhookEmitter, createPinAndBindFetch } from '@adcp/sdk/server';
114
+ *
115
+ * const emitter = createWebhookEmitter({
116
+ * signerKey: webhookKey,
117
+ * fetch: createPinAndBindFetch(),
118
+ * });
119
+ * ```
120
+ */
121
+ export declare function createPinAndBindFetch(options?: PinAndBindFetchOptions): typeof fetch;
@@ -0,0 +1,209 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+ var pin_and_bind_fetch_exports = {};
20
+ __export(pin_and_bind_fetch_exports, {
21
+ LOOPBACK_OK_WEBHOOK_SSRF_POLICY: () => LOOPBACK_OK_WEBHOOK_SSRF_POLICY,
22
+ WEBHOOK_SSRF_POLICY: () => WEBHOOK_SSRF_POLICY,
23
+ createPinAndBindFetch: () => createPinAndBindFetch
24
+ });
25
+ module.exports = __toCommonJS(pin_and_bind_fetch_exports);
26
+ var import_undici = require("undici");
27
+ var import_node_dns = require("node:dns");
28
+ var import_node_net = require("node:net");
29
+ var import_address_guards = require('./address-guards.js');
30
+ var import_ssrf = require('../substitution/observer/ssrf.js');
31
+ const WEBHOOK_SSRF_POLICY = Object.freeze({
32
+ schemes_allowed: Object.freeze(["https"]),
33
+ schemes_denied: Object.freeze(["http", "file", "gopher", "ftp", "ftps", "data", "javascript", "about", "ws", "wss"]),
34
+ hosts_denied_ipv4_cidrs: Object.freeze([
35
+ "0.0.0.0/8",
36
+ "10.0.0.0/8",
37
+ "100.64.0.0/10",
38
+ "127.0.0.0/8",
39
+ "169.254.0.0/16",
40
+ "172.16.0.0/12",
41
+ "192.0.0.0/24",
42
+ "192.168.0.0/16",
43
+ "224.0.0.0/4",
44
+ "240.0.0.0/4"
45
+ ]),
46
+ hosts_denied_ipv6_cidrs: Object.freeze([
47
+ "::1/128",
48
+ "::/128",
49
+ "::ffff:0:0/96",
50
+ "64:ff9b::/96",
51
+ "fc00::/7",
52
+ "fe80::/10",
53
+ "ff00::/8"
54
+ ]),
55
+ hosts_denied_metadata: Object.freeze([
56
+ "metadata.google.internal",
57
+ "metadata",
58
+ "metadata.packet.net",
59
+ "fd00:ec2::254"
60
+ ]),
61
+ host_literal_policy: "allow",
62
+ shared_private_address_policy: "deny"
63
+ });
64
+ const LOOPBACK_OK_WEBHOOK_SSRF_POLICY = Object.freeze({
65
+ schemes_allowed: Object.freeze(["http", "https"]),
66
+ schemes_denied: Object.freeze(["file", "gopher", "ftp", "ftps", "data", "javascript", "about", "ws", "wss"]),
67
+ hosts_denied_ipv4_cidrs: Object.freeze([
68
+ "0.0.0.0/8",
69
+ "10.0.0.0/8",
70
+ "100.64.0.0/10",
71
+ // 127.0.0.0/8 omitted — loopback allowed for tests.
72
+ "169.254.0.0/16",
73
+ "172.16.0.0/12",
74
+ "192.0.0.0/24",
75
+ "192.168.0.0/16",
76
+ "224.0.0.0/4",
77
+ "240.0.0.0/4"
78
+ ]),
79
+ hosts_denied_ipv6_cidrs: Object.freeze([
80
+ // ::1/128 and ::/128 omitted — IPv6 loopback allowed for tests.
81
+ "::ffff:0:0/96",
82
+ "64:ff9b::/96",
83
+ "fc00::/7",
84
+ "fe80::/10",
85
+ "ff00::/8"
86
+ ]),
87
+ hosts_denied_metadata: Object.freeze([
88
+ "metadata.google.internal",
89
+ "metadata",
90
+ "metadata.packet.net",
91
+ "fd00:ec2::254"
92
+ ]),
93
+ host_literal_policy: "allow",
94
+ shared_private_address_policy: "allow_loopback"
95
+ });
96
+ const DEFAULT_LOOKUP_ALL = (hostname, options, callback) => {
97
+ (0, import_node_dns.lookup)(hostname, { ...options, all: true }, (err, addresses) => {
98
+ callback(err, addresses);
99
+ });
100
+ };
101
+ function createPinAndBindFetch(options = {}) {
102
+ const policy = options.policy ?? WEBHOOK_SSRF_POLICY;
103
+ const lookupImpl = options.lookup ?? DEFAULT_LOOKUP_ALL;
104
+ const guardedLookup = (hostname, opts, callback) => {
105
+ const wantsAll = opts?.all === true;
106
+ lookupImpl(hostname, { ...opts ?? {}, all: true }, (err, addresses) => {
107
+ if (err) {
108
+ callback(err);
109
+ return;
110
+ }
111
+ if (!Array.isArray(addresses) || addresses.length === 0) {
112
+ callback(
113
+ makeSsrfError(`DNS resolution returned no addresses for ${hostname}`, "dns_revalidation:no_addresses")
114
+ );
115
+ return;
116
+ }
117
+ const url = new URL(`https://${bracketIfV6(hostname)}`);
118
+ const ips = addresses.map((a) => a.address);
119
+ if (ips.some(import_address_guards.isAlwaysBlocked)) {
120
+ callback(makeSsrfError(`Host ${hostname} resolves to an always-blocked address`, "always_blocked_address"));
121
+ return;
122
+ }
123
+ const result = (0, import_ssrf.enforceSsrfPolicyResolved)(url, ips, policy);
124
+ if (!result.allowed) {
125
+ callback(makeSsrfError(`Host ${hostname} resolves to an address denied by SSRF policy`, result.rule ?? "ssrf"));
126
+ return;
127
+ }
128
+ if (ips.some((ip) => isSharedPrivateAddressDenied(ip, policy))) {
129
+ callback(
130
+ makeSsrfError(
131
+ `Host ${hostname} resolves to a private, non-routable, or reserved address`,
132
+ "shared_private_address"
133
+ )
134
+ );
135
+ return;
136
+ }
137
+ if (wantsAll) {
138
+ callback(null, addresses);
139
+ return;
140
+ }
141
+ const first = addresses[0];
142
+ callback(null, first.address, first.family);
143
+ });
144
+ };
145
+ const dispatcher = new import_undici.Agent({
146
+ ...options.agentOptions ?? {},
147
+ connect: {
148
+ ...options.agentOptions?.connect ?? {},
149
+ // undici's connect type accepts a lookup with the dns.lookup signature.
150
+ lookup: guardedLookup
151
+ }
152
+ });
153
+ const wrapped = async (input, init) => {
154
+ const url = resolveRequestUrl(input);
155
+ if (!url) {
156
+ throw makeSsrfError("Unsupported or invalid URL input", "invalid_url");
157
+ }
158
+ const hostname = url.hostname.replace(/^\[|\]$/g, "");
159
+ if ((0, import_address_guards.isAlwaysBlocked)(hostname)) {
160
+ throw makeSsrfError(`Host ${hostname} is an always-blocked address`, "always_blocked_address");
161
+ }
162
+ const sync = (0, import_ssrf.enforceSsrfPolicy)(url, policy);
163
+ if (!sync.allowed) {
164
+ throw makeSsrfError(sync.message ?? "SSRF policy denied URL", sync.rule ?? "ssrf");
165
+ }
166
+ if (isSharedPrivateAddressDenied(hostname, policy)) {
167
+ throw makeSsrfError(`Host ${hostname} is a private, non-routable, or reserved address`, "shared_private_address");
168
+ }
169
+ const redirect = init?.redirect === "error" ? "error" : "manual";
170
+ const runtimeInput = input;
171
+ const checkedInput = runtimeInput instanceof globalThis.Request || runtimeInput instanceof import_undici.Request ? new import_undici.Request(url.href, runtimeInput) : url.href;
172
+ return (0, import_undici.fetch)(checkedInput, {
173
+ ...init,
174
+ redirect,
175
+ dispatcher
176
+ });
177
+ };
178
+ return wrapped;
179
+ }
180
+ function isSharedPrivateAddressDenied(address, policy) {
181
+ if (!(0, import_address_guards.isPrivateIp)(address)) return false;
182
+ if (policy.shared_private_address_policy === "deny") return true;
183
+ if (policy.shared_private_address_policy === "allow_loopback") return !(0, import_address_guards.isLoopbackIp)(address);
184
+ return false;
185
+ }
186
+ function resolveRequestUrl(input) {
187
+ try {
188
+ if (typeof input === "string") return new URL(input);
189
+ if (input instanceof URL) return new URL(input.href);
190
+ if (input instanceof globalThis.Request || input instanceof import_undici.Request) return new URL(input.url);
191
+ } catch {
192
+ return null;
193
+ }
194
+ return null;
195
+ }
196
+ function bracketIfV6(host) {
197
+ return (0, import_node_net.isIPv6)(host) ? `[${host}]` : host;
198
+ }
199
+ function makeSsrfError(message, rule) {
200
+ const err = new Error(`pin-and-bind: ${rule}: ${message}`);
201
+ err.code = "EADCP_SSRF_BLOCKED";
202
+ return err;
203
+ }
204
+ // Annotate the CommonJS export names for ESM import in node:
205
+ 0 && (module.exports = {
206
+ LOOPBACK_OK_WEBHOOK_SSRF_POLICY,
207
+ WEBHOOK_SSRF_POLICY,
208
+ createPinAndBindFetch
209
+ });