@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,108 @@
1
+ /**
2
+ * AdCP-layer validation for tools registered with a zod input schema.
3
+ *
4
+ * The MCP SDK parses `tools/call` arguments against a tool's registered
5
+ * `inputSchema` before the handler runs, and answers a failure with a bare
6
+ * `-32602` text result: no `structuredContent`, no `adcp_error`, and no echo
7
+ * of the caller's `context` (adcp-client#3666). Framework tools avoid that by
8
+ * registering a passthrough schema and validating inside the handler. These
9
+ * helpers give zod-declared tools (`customTools`, `tasks_get`,
10
+ * `comply_test_controller`) the same treatment:
11
+ *
12
+ * - {@link validateToolInputAtAdcpLayer} swaps the registered schema for a
13
+ * passthrough one, so MCP-level validation cannot reject first, and keeps
14
+ * `tools/list` advertising the declared schema.
15
+ * - {@link parseDeclaredToolInput} runs the declared schema inside the
16
+ * handler and returns either the parsed value (coercion, defaults and
17
+ * transforms applied exactly as the SDK applied them) or an
18
+ * `INVALID_REQUEST` response that echoes `context`.
19
+ *
20
+ * @internal
21
+ */
22
+ import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
23
+ import { type AnySchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
24
+ import type { McpToolResponse } from './responses';
25
+ /**
26
+ * Registered MCP input schema for tools whose arguments the AdCP layer
27
+ * validates. Accepts any object and keeps every key, so the handler sees the
28
+ * caller's arguments unchanged.
29
+ */
30
+ export declare const PASSTHROUGH_INPUT_SCHEMA: z.ZodObject<{}, z.core.$loose>;
31
+ /** What a framework-built rejection on a declared-input tool is finished from. */
32
+ export interface DeclaredInputRejection {
33
+ /** The caller's `context`, echoed verbatim. It never feeds a decision. */
34
+ context: unknown;
35
+ /**
36
+ * Arguments the served release is read from: the parsed value once parsing
37
+ * succeeded, the caller's arguments when parsing itself failed.
38
+ */
39
+ releaseArgs: unknown;
40
+ }
41
+ /**
42
+ * Finishes a framework-built rejection the way the hosting server finishes its
43
+ * own errors: the caller's `context`, envelope `status`, served `adcp_version`.
44
+ */
45
+ export type DeclaredInputErrorFinalizer = (toolName: string, response: McpToolResponse, rejection: DeclaredInputRejection) => McpToolResponse;
46
+ /**
47
+ * Configure how declared-input errors on `server` are finished. Called by
48
+ * `createAdcpServer` so tools registered after it returns (the
49
+ * `comply_test_controller` helpers) stamp the same envelope fields as
50
+ * framework errors. Without it, errors still carry `adcp_error` and `context`.
51
+ */
52
+ export declare function configureDeclaredInputErrors(server: McpServer, options: {
53
+ finalize: DeclaredInputErrorFinalizer;
54
+ exposeSchemaPath: boolean;
55
+ }): void;
56
+ /**
57
+ * Move a freshly registered tool's argument validation from the MCP SDK to
58
+ * the AdCP layer. The schema the SDK normalized at registration becomes the
59
+ * declared schema: {@link parseDeclaredToolInput} validates against it and
60
+ * `tools/list` keeps advertising it. The SDK itself validates against
61
+ * {@link PASSTHROUGH_INPUT_SCHEMA} from now on.
62
+ *
63
+ * The handler must call {@link parseDeclaredToolInput} before using its
64
+ * arguments. A tool registered without an input schema is left unchanged, and
65
+ * so is a tool on a server that is not an SDK `McpServer` (a test double or
66
+ * proxy that returns no registration record or has no `tools/list` handler to
67
+ * wrap): its SDK keeps validating, and {@link parseDeclaredToolInput} passes
68
+ * the arguments through.
69
+ */
70
+ export declare function validateToolInputAtAdcpLayer(server: McpServer, name: string, registered: Pick<RegisteredTool, 'inputSchema'> | {
71
+ inputSchema?: unknown;
72
+ } | undefined): void;
73
+ /** The declared input schema of `name` on `server`, when the AdCP layer validates it. */
74
+ export declare function getDeclaredInputSchema(server: McpServer, name: string): AnySchema | undefined;
75
+ /** The JSON Schema the MCP SDK's own `tools/list` emits for an input schema. */
76
+ export declare function declaredInputJsonSchema(schema: AnySchema): Record<string, unknown>;
77
+ export type DeclaredInputParseResult = {
78
+ success: true;
79
+ data: unknown;
80
+ } | {
81
+ success: false;
82
+ response: McpToolResponse;
83
+ };
84
+ /**
85
+ * Validate `args` against the schema `name` declared at registration.
86
+ *
87
+ * Success carries the parsed value — the same value the MCP SDK used to hand
88
+ * the handler, with zod coercion, defaults and transforms applied. Every
89
+ * decision the caller makes afterwards (authorization, release selection,
90
+ * gating) must read this value and hand the handler this same value; reading
91
+ * the raw arguments again would let a default or coercion change what was
92
+ * authorized. Failure carries an `INVALID_REQUEST` response with `field`
93
+ * naming the first failing path, the field-level `issues`, and the caller's
94
+ * `context` echoed. A tool without a declared schema passes `args` through.
95
+ *
96
+ * `options.echoContext` maps the caller's `context` before it is echoed, so
97
+ * a tool that bounds its echoes (the platform `comply_test_controller` caps
98
+ * them at 8 KiB) bounds this one too.
99
+ */
100
+ export declare function parseDeclaredToolInput(server: McpServer, name: string, args: unknown, options?: {
101
+ echoContext?: (context: unknown) => unknown;
102
+ }): Promise<DeclaredInputParseResult>;
103
+ /**
104
+ * Finish a framework-built rejection of `name` the way its `INVALID_REQUEST`
105
+ * is finished: with the hosting server's finalizer, or on a server without
106
+ * one, by echoing the caller's `context`.
107
+ */
108
+ export declare function finishDeclaredInputRejection(server: McpServer, name: string, response: McpToolResponse, rejection: DeclaredInputRejection): McpToolResponse;
@@ -0,0 +1,167 @@
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 declared_input_schema_exports = {};
20
+ __export(declared_input_schema_exports, {
21
+ PASSTHROUGH_INPUT_SCHEMA: () => PASSTHROUGH_INPUT_SCHEMA,
22
+ configureDeclaredInputErrors: () => configureDeclaredInputErrors,
23
+ declaredInputJsonSchema: () => declaredInputJsonSchema,
24
+ finishDeclaredInputRejection: () => finishDeclaredInputRejection,
25
+ getDeclaredInputSchema: () => getDeclaredInputSchema,
26
+ parseDeclaredToolInput: () => parseDeclaredToolInput,
27
+ validateToolInputAtAdcpLayer: () => validateToolInputAtAdcpLayer
28
+ });
29
+ module.exports = __toCommonJS(declared_input_schema_exports);
30
+ var import_zod = require("zod");
31
+ var import_zod_compat = require("@modelcontextprotocol/sdk/server/zod-compat.js");
32
+ var import_zod_json_schema_compat = require("@modelcontextprotocol/sdk/server/zod-json-schema-compat.js");
33
+ var import_adcp_server = require('./adcp-server.js');
34
+ var import_errors = require('./errors.js');
35
+ var import_schema_errors = require('../validation/schema-errors.js');
36
+ const PASSTHROUGH_INPUT_SCHEMA = import_zod.z.object({}).passthrough();
37
+ const states = /* @__PURE__ */ new WeakMap();
38
+ function stateFor(server) {
39
+ let state = states.get(server);
40
+ if (state === void 0) {
41
+ state = { schemas: /* @__PURE__ */ new Map(), discoveryInstalled: false };
42
+ states.set(server, state);
43
+ }
44
+ return state;
45
+ }
46
+ function isPlainObject(value) {
47
+ return value !== null && typeof value === "object" && !Array.isArray(value);
48
+ }
49
+ function configureDeclaredInputErrors(server, options) {
50
+ const state = stateFor(server);
51
+ state.finalizeError = options.finalize;
52
+ state.exposeSchemaPath = options.exposeSchemaPath;
53
+ }
54
+ function validateToolInputAtAdcpLayer(server, name, registered) {
55
+ const declared = registered?.inputSchema;
56
+ if (registered === void 0 || declared === void 0) return;
57
+ const state = stateFor(server);
58
+ state.discoveryInstalled ||= (0, import_adcp_server.wrapSdkRequestHandler)(
59
+ server,
60
+ "tools/list",
61
+ async (original, request, extra) => advertiseDeclaredInputSchemas(await original(request, extra), state.schemas)
62
+ );
63
+ if (!state.discoveryInstalled) return;
64
+ state.schemas.set(name, declared);
65
+ registered.inputSchema = PASSTHROUGH_INPUT_SCHEMA;
66
+ }
67
+ function getDeclaredInputSchema(server, name) {
68
+ return states.get(server)?.schemas.get(name);
69
+ }
70
+ function declaredInputJsonSchema(schema) {
71
+ const objectSchema = (0, import_zod_compat.normalizeObjectSchema)(schema);
72
+ return objectSchema ? (0, import_zod_json_schema_compat.toJsonSchemaCompat)(objectSchema, { strictUnions: true, pipeStrategy: "input" }) : { type: "object", properties: {} };
73
+ }
74
+ function advertiseDeclaredInputSchemas(response, schemas) {
75
+ if (!isPlainObject(response) || !Array.isArray(response.tools)) return response;
76
+ return {
77
+ ...response,
78
+ tools: response.tools.map((tool) => {
79
+ const name = isPlainObject(tool) ? tool.name : void 0;
80
+ const declared = typeof name === "string" ? schemas.get(name) : void 0;
81
+ return declared === void 0 ? tool : { ...tool, inputSchema: declaredInputJsonSchema(declared) };
82
+ })
83
+ };
84
+ }
85
+ async function parseDeclaredToolInput(server, name, args, options = {}) {
86
+ const state = states.get(server);
87
+ const declared = state?.schemas.get(name);
88
+ if (state === void 0 || declared === void 0) return { success: true, data: args };
89
+ const input = args ?? {};
90
+ const result = await (0, import_zod_compat.safeParseAsync)((0, import_zod_compat.normalizeObjectSchema)(declared) ?? declared, input);
91
+ if (result.success) return { success: true, data: result.data };
92
+ const payload = (0, import_schema_errors.buildAdcpValidationErrorPayload)(name, "request", zodIssuesToValidationIssues(result.error, input), {
93
+ exposeSchemaPath: state.exposeSchemaPath === true
94
+ });
95
+ const callerContext = isPlainObject(input) ? input.context : void 0;
96
+ const context = options.echoContext ? options.echoContext(callerContext) : callerContext;
97
+ return {
98
+ success: false,
99
+ response: finishDeclaredInputRejection(server, name, (0, import_errors.adcpError)("INVALID_REQUEST", payload), {
100
+ context,
101
+ releaseArgs: input
102
+ })
103
+ };
104
+ }
105
+ function finishDeclaredInputRejection(server, name, response, rejection) {
106
+ const finalize = states.get(server)?.finalizeError;
107
+ if (finalize !== void 0) return finalize(name, response, rejection);
108
+ const structured = response.structuredContent;
109
+ if (!isPlainObject(rejection.context) || !isPlainObject(structured) || "context" in structured) return response;
110
+ const text = response.content?.[0];
111
+ const mirrors = text?.type === "text" && text.text === JSON.stringify(structured);
112
+ structured.context = rejection.context;
113
+ if (mirrors) text.text = JSON.stringify(structured);
114
+ return response;
115
+ }
116
+ function escapePointerSegment(segment) {
117
+ return String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
118
+ }
119
+ function isMissingAt(value, path) {
120
+ let parent = value;
121
+ for (const segment of path.slice(0, -1)) {
122
+ if (parent === null || typeof parent !== "object") return false;
123
+ parent = parent[segment];
124
+ }
125
+ if (parent === null || typeof parent !== "object") return false;
126
+ return parent[path[path.length - 1]] === void 0;
127
+ }
128
+ function toValidationIssue(path, keyword, message) {
129
+ return {
130
+ pointer: path.map((segment) => `/${escapePointerSegment(segment)}`).join(""),
131
+ message,
132
+ keyword,
133
+ schemaPath: `#${path.map((segment) => typeof segment === "number" ? "/items" : `/properties/${escapePointerSegment(segment)}`).join("")}/${keyword}`
134
+ };
135
+ }
136
+ function zodIssuesToValidationIssues(error, input) {
137
+ const zodIssues = isPlainObject(error) ? error.issues : void 0;
138
+ if (!Array.isArray(zodIssues) || zodIssues.length === 0) {
139
+ return [toValidationIssue([], "type", "Invalid arguments")];
140
+ }
141
+ return zodIssues.flatMap((raw) => {
142
+ const issue = isPlainObject(raw) ? raw : {};
143
+ const path = (Array.isArray(issue.path) ? issue.path : []).filter(
144
+ (segment) => typeof segment === "string" || typeof segment === "number"
145
+ );
146
+ if (issue.code === "unrecognized_keys" && Array.isArray(issue.keys)) {
147
+ return issue.keys.map(
148
+ (key) => toValidationIssue([...path, String(key)], "additionalProperties", `must NOT have additional property '${key}'`)
149
+ );
150
+ }
151
+ if (path.length > 0 && isMissingAt(input, path)) {
152
+ return [toValidationIssue(path, "required", `must have required property '${path[path.length - 1]}'`)];
153
+ }
154
+ const message = typeof issue.message === "string" ? issue.message : "Invalid value";
155
+ return [toValidationIssue(path, typeof issue.code === "string" ? issue.code : "type", message)];
156
+ });
157
+ }
158
+ // Annotate the CommonJS export names for ESM import in node:
159
+ 0 && (module.exports = {
160
+ PASSTHROUGH_INPUT_SCHEMA,
161
+ configureDeclaredInputErrors,
162
+ declaredInputJsonSchema,
163
+ finishDeclaredInputRejection,
164
+ getDeclaredInputSchema,
165
+ parseDeclaredToolInput,
166
+ validateToolInputAtAdcpLayer
167
+ });
@@ -0,0 +1,137 @@
1
+ import { z } from "zod";
2
+ import { normalizeObjectSchema, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
3
+ import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
4
+ import { wrapSdkRequestHandler } from "./adcp-server.mjs";
5
+ import { adcpError } from "./errors.mjs";
6
+ import { buildAdcpValidationErrorPayload } from "../validation/schema-errors.mjs";
7
+ const PASSTHROUGH_INPUT_SCHEMA = z.object({}).passthrough();
8
+ const states = /* @__PURE__ */ new WeakMap();
9
+ function stateFor(server) {
10
+ let state = states.get(server);
11
+ if (state === void 0) {
12
+ state = { schemas: /* @__PURE__ */ new Map(), discoveryInstalled: false };
13
+ states.set(server, state);
14
+ }
15
+ return state;
16
+ }
17
+ function isPlainObject(value) {
18
+ return value !== null && typeof value === "object" && !Array.isArray(value);
19
+ }
20
+ function configureDeclaredInputErrors(server, options) {
21
+ const state = stateFor(server);
22
+ state.finalizeError = options.finalize;
23
+ state.exposeSchemaPath = options.exposeSchemaPath;
24
+ }
25
+ function validateToolInputAtAdcpLayer(server, name, registered) {
26
+ const declared = registered?.inputSchema;
27
+ if (registered === void 0 || declared === void 0) return;
28
+ const state = stateFor(server);
29
+ state.discoveryInstalled ||= wrapSdkRequestHandler(
30
+ server,
31
+ "tools/list",
32
+ async (original, request, extra) => advertiseDeclaredInputSchemas(await original(request, extra), state.schemas)
33
+ );
34
+ if (!state.discoveryInstalled) return;
35
+ state.schemas.set(name, declared);
36
+ registered.inputSchema = PASSTHROUGH_INPUT_SCHEMA;
37
+ }
38
+ function getDeclaredInputSchema(server, name) {
39
+ return states.get(server)?.schemas.get(name);
40
+ }
41
+ function declaredInputJsonSchema(schema) {
42
+ const objectSchema = normalizeObjectSchema(schema);
43
+ return objectSchema ? toJsonSchemaCompat(objectSchema, { strictUnions: true, pipeStrategy: "input" }) : { type: "object", properties: {} };
44
+ }
45
+ function advertiseDeclaredInputSchemas(response, schemas) {
46
+ if (!isPlainObject(response) || !Array.isArray(response.tools)) return response;
47
+ return {
48
+ ...response,
49
+ tools: response.tools.map((tool) => {
50
+ const name = isPlainObject(tool) ? tool.name : void 0;
51
+ const declared = typeof name === "string" ? schemas.get(name) : void 0;
52
+ return declared === void 0 ? tool : { ...tool, inputSchema: declaredInputJsonSchema(declared) };
53
+ })
54
+ };
55
+ }
56
+ async function parseDeclaredToolInput(server, name, args, options = {}) {
57
+ const state = states.get(server);
58
+ const declared = state?.schemas.get(name);
59
+ if (state === void 0 || declared === void 0) return { success: true, data: args };
60
+ const input = args ?? {};
61
+ const result = await safeParseAsync(normalizeObjectSchema(declared) ?? declared, input);
62
+ if (result.success) return { success: true, data: result.data };
63
+ const payload = buildAdcpValidationErrorPayload(name, "request", zodIssuesToValidationIssues(result.error, input), {
64
+ exposeSchemaPath: state.exposeSchemaPath === true
65
+ });
66
+ const callerContext = isPlainObject(input) ? input.context : void 0;
67
+ const context = options.echoContext ? options.echoContext(callerContext) : callerContext;
68
+ return {
69
+ success: false,
70
+ response: finishDeclaredInputRejection(server, name, adcpError("INVALID_REQUEST", payload), {
71
+ context,
72
+ releaseArgs: input
73
+ })
74
+ };
75
+ }
76
+ function finishDeclaredInputRejection(server, name, response, rejection) {
77
+ const finalize = states.get(server)?.finalizeError;
78
+ if (finalize !== void 0) return finalize(name, response, rejection);
79
+ const structured = response.structuredContent;
80
+ if (!isPlainObject(rejection.context) || !isPlainObject(structured) || "context" in structured) return response;
81
+ const text = response.content?.[0];
82
+ const mirrors = text?.type === "text" && text.text === JSON.stringify(structured);
83
+ structured.context = rejection.context;
84
+ if (mirrors) text.text = JSON.stringify(structured);
85
+ return response;
86
+ }
87
+ function escapePointerSegment(segment) {
88
+ return String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
89
+ }
90
+ function isMissingAt(value, path) {
91
+ let parent = value;
92
+ for (const segment of path.slice(0, -1)) {
93
+ if (parent === null || typeof parent !== "object") return false;
94
+ parent = parent[segment];
95
+ }
96
+ if (parent === null || typeof parent !== "object") return false;
97
+ return parent[path[path.length - 1]] === void 0;
98
+ }
99
+ function toValidationIssue(path, keyword, message) {
100
+ return {
101
+ pointer: path.map((segment) => `/${escapePointerSegment(segment)}`).join(""),
102
+ message,
103
+ keyword,
104
+ schemaPath: `#${path.map((segment) => typeof segment === "number" ? "/items" : `/properties/${escapePointerSegment(segment)}`).join("")}/${keyword}`
105
+ };
106
+ }
107
+ function zodIssuesToValidationIssues(error, input) {
108
+ const zodIssues = isPlainObject(error) ? error.issues : void 0;
109
+ if (!Array.isArray(zodIssues) || zodIssues.length === 0) {
110
+ return [toValidationIssue([], "type", "Invalid arguments")];
111
+ }
112
+ return zodIssues.flatMap((raw) => {
113
+ const issue = isPlainObject(raw) ? raw : {};
114
+ const path = (Array.isArray(issue.path) ? issue.path : []).filter(
115
+ (segment) => typeof segment === "string" || typeof segment === "number"
116
+ );
117
+ if (issue.code === "unrecognized_keys" && Array.isArray(issue.keys)) {
118
+ return issue.keys.map(
119
+ (key) => toValidationIssue([...path, String(key)], "additionalProperties", `must NOT have additional property '${key}'`)
120
+ );
121
+ }
122
+ if (path.length > 0 && isMissingAt(input, path)) {
123
+ return [toValidationIssue(path, "required", `must have required property '${path[path.length - 1]}'`)];
124
+ }
125
+ const message = typeof issue.message === "string" ? issue.message : "Invalid value";
126
+ return [toValidationIssue(path, typeof issue.code === "string" ? issue.code : "type", message)];
127
+ });
128
+ }
129
+ export {
130
+ PASSTHROUGH_INPUT_SCHEMA,
131
+ configureDeclaredInputErrors,
132
+ declaredInputJsonSchema,
133
+ finishDeclaredInputRejection,
134
+ getDeclaredInputSchema,
135
+ parseDeclaredToolInput,
136
+ validateToolInputAtAdcpLayer
137
+ };
@@ -1,105 +1 @@
1
- /**
2
- * Envelope-allowlist governance for AdCP error responses.
3
- *
4
- * Two orthogonal concerns both govern what round-trips on an AdCP error
5
- * envelope. They live side-by-side here so that a change to one forces
6
- * the reviewer to weigh the other (security review M4 on #788 — the
7
- * pair is conceptually related and can drift in separate files).
8
- *
9
- * - `ERROR_ENVELOPE_FIELD_ALLOWLIST` governs keys that may appear as
10
- * SIBLINGS of `adcp_error` on the wire response. Enforced by
11
- * `wrapEnvelope` in `./wrap-envelope.ts`.
12
- * - `ADCP_ERROR_FIELD_ALLOWLIST` governs keys that may appear INSIDE
13
- * the `adcp_error` block, keyed by error code. Consumed by
14
- * `adcpError()` (which filters its output to the allowlisted set)
15
- * AND by the dispatcher in `create-adcp-server.ts` (re-applied to
16
- * every handler-returned envelope via `sanitizeAdcpErrorEnvelope`
17
- * — defence-in-depth for handlers that hand-roll an error envelope
18
- * instead of going through the builder). The same set powers the
19
- * `idempotency.conflict_no_payload_leak` invariant in
20
- * `../testing/storyboard/default-invariants.ts`. The legacy
21
- * `CONFLICT_ADCP_ERROR_ALLOWLIST` export is a convenience alias for
22
- * the `IDEMPOTENCY_CONFLICT` entry.
23
- *
24
- * Both sets apply to the same wire response but at different nesting
25
- * levels. A seller that needs to extend one should audit whether the
26
- * other also needs updating.
27
- *
28
- * Hand-rolling an error envelope? Prefer `adcpError(code, options)` —
29
- * it wraps both transport layers and applies this allowlist for you.
30
- * The dispatcher sanitizer is a belt-and-suspenders, not a primary API.
31
- */
32
- /**
33
- * Fail-closed default allowlist for unknown error codes.
34
- *
35
- * An error code without an explicit entry in
36
- * `ERROR_ENVELOPE_FIELD_ALLOWLIST` gets this set — only `context`
37
- * round-trips (matching the invariant that every allowlist permits
38
- * correlation tracing). Sellers that want `replayed` or `operation_id`
39
- * on a bespoke error code must register it explicitly.
40
- *
41
- * This is the fail-closed posture — sellers MUST opt in to any field
42
- * they want on an error envelope, rather than inheriting success-path
43
- * semantics by default. Security review M3 on #788.
44
- */
45
- export declare const DEFAULT_ERROR_ENVELOPE_FIELDS: ReadonlySet<string>;
46
- /**
47
- * Per-error-code envelope-field allowlist.
48
- *
49
- * A code listed here restricts which envelope fields `wrapEnvelope`
50
- * will attach on top of the error's inner payload. Codes NOT listed
51
- * here receive `DEFAULT_ERROR_ENVELOPE_FIELDS` (fail-closed —
52
- * `context` only).
53
- *
54
- * `IDEMPOTENCY_CONFLICT` deliberately excludes `replayed`: the
55
- * conflict path in `create-adcp-server.ts` builds its error via
56
- * `finalize()`, which only echoes `context` and never calls
57
- * `stampReplayed`. The framework's own behavior is preserved.
58
- *
59
- * **Invariant**: every allowlist set MUST include `'context'`.
60
- * `ensureContextEcho` enforces this at module load so new error codes
61
- * can't accidentally drop context echo (which sellers rely on for
62
- * correlation tracing across both success and error paths).
63
- */
64
- export declare const ERROR_ENVELOPE_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
65
- /**
66
- * Per-error-code allowlist for keys permitted INSIDE the `adcp_error`
67
- * block. The `adcpError()` builder consults this table and drops any
68
- * field the caller passes that isn't allowlisted for the given code —
69
- * the allowlist IS the contract for what a framework-emitted error may
70
- * carry. Storyboard invariants enforce the same contract on the wire.
71
- *
72
- * A code without an explicit entry permits everything `adcpError()`
73
- * would otherwise emit — the default case is pass-through. Sellers who
74
- * want a bespoke code to be strict should register it here (or wrap
75
- * `adcpError()` with their own sanitizer).
76
- *
77
- * **Scope warning for future contributors:** only register a code here
78
- * if it belongs to the AdCP standard error vocabulary (`enums/error-code.json`).
79
- * Per `core/error.json`, clients "MUST handle unknown codes gracefully
80
- * by falling back to the recovery classification" — so dropping
81
- * `recovery` on a vendor / non-standard code makes the response
82
- * genuinely lossy for any buyer agent that doesn't have the code in
83
- * its local vocabulary.
84
- *
85
- * `IDEMPOTENCY_CONFLICT` is narrow on purpose: a conflict response MUST
86
- * NOT echo the prior request payload or cached response (stolen-key
87
- * read oracle defence). Standard recovery metadata is allowed because it
88
- * is normalized to the fixed classifier, not trusted as caller-provided
89
- * prior request or cached response data.
90
- * `retry_after` is excluded: no framework path currently emits it on conflict, and a seller
91
- * that computed `retry_after = cached_entry_age` would leak the prior
92
- * payload's creation time (a distinguisher between "key never seen" vs
93
- * "key seen N seconds ago"). Retry hints belong on transient codes
94
- * (`SERVICE_UNAVAILABLE`, `RATE_LIMITED`), not on a terminal conflict.
95
- * `adcpError()` and the dispatcher sanitizer both enforce this.
96
- */
97
- export declare const ADCP_ERROR_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
98
- /**
99
- * Convenience alias for the `IDEMPOTENCY_CONFLICT` entry in
100
- * {@link ADCP_ERROR_FIELD_ALLOWLIST}. Kept as a named export because
101
- * the default `idempotency.conflict_no_payload_leak` invariant and a
102
- * handful of consumer tests reach for it by name; new code should use
103
- * `ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT` directly.
104
- */
105
- export declare const CONFLICT_ADCP_ERROR_ALLOWLIST: ReadonlySet<string>;
1
+ export * from '../utils/envelope-allowlist.mjs';
@@ -1,105 +1 @@
1
- /**
2
- * Envelope-allowlist governance for AdCP error responses.
3
- *
4
- * Two orthogonal concerns both govern what round-trips on an AdCP error
5
- * envelope. They live side-by-side here so that a change to one forces
6
- * the reviewer to weigh the other (security review M4 on #788 — the
7
- * pair is conceptually related and can drift in separate files).
8
- *
9
- * - `ERROR_ENVELOPE_FIELD_ALLOWLIST` governs keys that may appear as
10
- * SIBLINGS of `adcp_error` on the wire response. Enforced by
11
- * `wrapEnvelope` in `./wrap-envelope.ts`.
12
- * - `ADCP_ERROR_FIELD_ALLOWLIST` governs keys that may appear INSIDE
13
- * the `adcp_error` block, keyed by error code. Consumed by
14
- * `adcpError()` (which filters its output to the allowlisted set)
15
- * AND by the dispatcher in `create-adcp-server.ts` (re-applied to
16
- * every handler-returned envelope via `sanitizeAdcpErrorEnvelope`
17
- * — defence-in-depth for handlers that hand-roll an error envelope
18
- * instead of going through the builder). The same set powers the
19
- * `idempotency.conflict_no_payload_leak` invariant in
20
- * `../testing/storyboard/default-invariants.ts`. The legacy
21
- * `CONFLICT_ADCP_ERROR_ALLOWLIST` export is a convenience alias for
22
- * the `IDEMPOTENCY_CONFLICT` entry.
23
- *
24
- * Both sets apply to the same wire response but at different nesting
25
- * levels. A seller that needs to extend one should audit whether the
26
- * other also needs updating.
27
- *
28
- * Hand-rolling an error envelope? Prefer `adcpError(code, options)` —
29
- * it wraps both transport layers and applies this allowlist for you.
30
- * The dispatcher sanitizer is a belt-and-suspenders, not a primary API.
31
- */
32
- /**
33
- * Fail-closed default allowlist for unknown error codes.
34
- *
35
- * An error code without an explicit entry in
36
- * `ERROR_ENVELOPE_FIELD_ALLOWLIST` gets this set — only `context`
37
- * round-trips (matching the invariant that every allowlist permits
38
- * correlation tracing). Sellers that want `replayed` or `operation_id`
39
- * on a bespoke error code must register it explicitly.
40
- *
41
- * This is the fail-closed posture — sellers MUST opt in to any field
42
- * they want on an error envelope, rather than inheriting success-path
43
- * semantics by default. Security review M3 on #788.
44
- */
45
- export declare const DEFAULT_ERROR_ENVELOPE_FIELDS: ReadonlySet<string>;
46
- /**
47
- * Per-error-code envelope-field allowlist.
48
- *
49
- * A code listed here restricts which envelope fields `wrapEnvelope`
50
- * will attach on top of the error's inner payload. Codes NOT listed
51
- * here receive `DEFAULT_ERROR_ENVELOPE_FIELDS` (fail-closed —
52
- * `context` only).
53
- *
54
- * `IDEMPOTENCY_CONFLICT` deliberately excludes `replayed`: the
55
- * conflict path in `create-adcp-server.ts` builds its error via
56
- * `finalize()`, which only echoes `context` and never calls
57
- * `stampReplayed`. The framework's own behavior is preserved.
58
- *
59
- * **Invariant**: every allowlist set MUST include `'context'`.
60
- * `ensureContextEcho` enforces this at module load so new error codes
61
- * can't accidentally drop context echo (which sellers rely on for
62
- * correlation tracing across both success and error paths).
63
- */
64
- export declare const ERROR_ENVELOPE_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
65
- /**
66
- * Per-error-code allowlist for keys permitted INSIDE the `adcp_error`
67
- * block. The `adcpError()` builder consults this table and drops any
68
- * field the caller passes that isn't allowlisted for the given code —
69
- * the allowlist IS the contract for what a framework-emitted error may
70
- * carry. Storyboard invariants enforce the same contract on the wire.
71
- *
72
- * A code without an explicit entry permits everything `adcpError()`
73
- * would otherwise emit — the default case is pass-through. Sellers who
74
- * want a bespoke code to be strict should register it here (or wrap
75
- * `adcpError()` with their own sanitizer).
76
- *
77
- * **Scope warning for future contributors:** only register a code here
78
- * if it belongs to the AdCP standard error vocabulary (`enums/error-code.json`).
79
- * Per `core/error.json`, clients "MUST handle unknown codes gracefully
80
- * by falling back to the recovery classification" — so dropping
81
- * `recovery` on a vendor / non-standard code makes the response
82
- * genuinely lossy for any buyer agent that doesn't have the code in
83
- * its local vocabulary.
84
- *
85
- * `IDEMPOTENCY_CONFLICT` is narrow on purpose: a conflict response MUST
86
- * NOT echo the prior request payload or cached response (stolen-key
87
- * read oracle defence). Standard recovery metadata is allowed because it
88
- * is normalized to the fixed classifier, not trusted as caller-provided
89
- * prior request or cached response data.
90
- * `retry_after` is excluded: no framework path currently emits it on conflict, and a seller
91
- * that computed `retry_after = cached_entry_age` would leak the prior
92
- * payload's creation time (a distinguisher between "key never seen" vs
93
- * "key seen N seconds ago"). Retry hints belong on transient codes
94
- * (`SERVICE_UNAVAILABLE`, `RATE_LIMITED`), not on a terminal conflict.
95
- * `adcpError()` and the dispatcher sanitizer both enforce this.
96
- */
97
- export declare const ADCP_ERROR_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
98
- /**
99
- * Convenience alias for the `IDEMPOTENCY_CONFLICT` entry in
100
- * {@link ADCP_ERROR_FIELD_ALLOWLIST}. Kept as a named export because
101
- * the default `idempotency.conflict_no_payload_leak` invariant and a
102
- * handful of consumer tests reach for it by name; new code should use
103
- * `ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT` directly.
104
- */
105
- export declare const CONFLICT_ADCP_ERROR_ALLOWLIST: ReadonlySet<string>;
1
+ export * from '../utils/envelope-allowlist';