@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.
- package/README.md +26 -2
- package/dist/lib/adapters/version/index.d.mts +1 -1
- package/dist/lib/adapters/version/index.d.ts +1 -1
- package/dist/lib/adapters/version/index.js +2 -0
- package/dist/lib/adapters/version/index.mjs +2 -0
- package/dist/lib/adapters/version/negotiate.d.mts +13 -0
- package/dist/lib/adapters/version/negotiate.d.ts +13 -0
- package/dist/lib/adapters/version/negotiate.js +6 -0
- package/dist/lib/adapters/version/negotiate.mjs +5 -0
- package/dist/lib/client/core.d.mts +4 -0
- package/dist/lib/client/core.d.ts +4 -0
- package/dist/lib/client/core.js +13 -0
- package/dist/lib/client/core.mjs +12 -0
- package/dist/lib/conformance/property-lists.d.mts +1 -1
- package/dist/lib/conformance/property-lists.d.ts +1 -1
- package/dist/lib/conformance/property-lists.js +1 -1
- package/dist/lib/conformance/property-lists.mjs +1 -1
- package/dist/lib/core/SingleAgentClient.d.mts +23 -1
- package/dist/lib/core/SingleAgentClient.d.ts +23 -1
- package/dist/lib/core/SingleAgentClient.js +102 -18
- package/dist/lib/core/SingleAgentClient.mjs +108 -18
- package/dist/lib/core/targeting-helpers.d.mts +123 -0
- package/dist/lib/core/targeting-helpers.d.ts +123 -0
- package/dist/lib/core/targeting-helpers.js +412 -0
- package/dist/lib/core/targeting-helpers.mjs +370 -0
- package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
- package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
- package/dist/lib/entrypoints/client-account-changes.js +28 -0
- package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
- package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
- package/dist/lib/entrypoints/discovery.d.mts +9 -0
- package/dist/lib/entrypoints/discovery.d.ts +9 -0
- package/dist/lib/entrypoints/discovery.js +72 -0
- package/dist/lib/entrypoints/discovery.mjs +56 -0
- package/dist/lib/entrypoints/errors.d.mts +11 -0
- package/dist/lib/entrypoints/errors.d.ts +11 -0
- package/dist/lib/entrypoints/errors.js +159 -0
- package/dist/lib/entrypoints/errors.mjs +132 -0
- package/dist/lib/entrypoints/media-buy.d.mts +5 -0
- package/dist/lib/entrypoints/media-buy.d.ts +5 -0
- package/dist/lib/entrypoints/media-buy.js +119 -0
- package/dist/lib/entrypoints/media-buy.mjs +100 -0
- package/dist/lib/entrypoints/registry.d.mts +5 -0
- package/dist/lib/entrypoints/registry.d.ts +5 -0
- package/dist/lib/entrypoints/registry.js +61 -0
- package/dist/lib/entrypoints/registry.mjs +40 -0
- package/dist/lib/entrypoints/utils.d.mts +7 -0
- package/dist/lib/entrypoints/utils.d.ts +7 -0
- package/dist/lib/entrypoints/utils.js +100 -0
- package/dist/lib/entrypoints/utils.mjs +72 -0
- package/dist/lib/entrypoints/version.d.mts +3 -0
- package/dist/lib/entrypoints/version.d.ts +3 -0
- package/dist/lib/entrypoints/version.js +57 -0
- package/dist/lib/entrypoints/version.mjs +36 -0
- package/dist/lib/index.d.mts +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/media-buy/action-contracts.js +3 -3
- package/dist/lib/media-buy/action-contracts.mjs +1 -1
- package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
- package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
- package/dist/lib/media-buy/creative-start-policy.js +59 -0
- package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
- package/dist/lib/media-buy/valid-actions.d.mts +47 -0
- package/dist/lib/media-buy/valid-actions.d.ts +47 -0
- package/dist/lib/media-buy/valid-actions.js +42 -0
- package/dist/lib/media-buy/valid-actions.mjs +18 -0
- package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.js +209 -0
- package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
- package/dist/lib/protocols/mcp-modern.js +20 -4
- package/dist/lib/protocols/mcp-modern.mjs +20 -4
- package/dist/lib/registry/types.generated.d.ts +224 -3
- package/dist/lib/reporting/ledger/index.d.mts +1 -0
- package/dist/lib/reporting/ledger/index.d.ts +1 -0
- package/dist/lib/reporting/ledger/index.js +3 -1
- package/dist/lib/reporting/ledger/index.mjs +1 -0
- package/dist/lib/reporting/ledger/instant.d.mts +5 -0
- package/dist/lib/reporting/ledger/instant.d.ts +5 -0
- package/dist/lib/reporting/ledger/instant.js +10 -0
- package/dist/lib/reporting/ledger/instant.mjs +9 -0
- package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
- package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
- package/dist/lib/reporting/ledger/issue-events.js +310 -0
- package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
- package/dist/lib/reporting/service/index.d.mts +36 -1
- package/dist/lib/reporting/service/index.d.ts +36 -1
- package/dist/lib/reporting/service/index.js +51 -1
- package/dist/lib/reporting/service/index.mjs +52 -2
- package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
- package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
- package/dist/lib/reporting/service/scheduler-support.js +1 -1
- package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
- package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
- package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
- package/dist/lib/server/capabilities-release-projection.js +128 -0
- package/dist/lib/server/capabilities-release-projection.mjs +112 -0
- package/dist/lib/server/create-adcp-server.d.mts +29 -5
- package/dist/lib/server/create-adcp-server.d.ts +29 -5
- package/dist/lib/server/create-adcp-server.js +97 -24
- package/dist/lib/server/create-adcp-server.mjs +108 -23
- package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
- package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
- package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
- package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
- package/dist/lib/server/declared-input-schema.d.mts +108 -0
- package/dist/lib/server/declared-input-schema.d.ts +108 -0
- package/dist/lib/server/declared-input-schema.js +167 -0
- package/dist/lib/server/declared-input-schema.mjs +137 -0
- package/dist/lib/server/envelope-allowlist.d.mts +1 -105
- package/dist/lib/server/envelope-allowlist.d.ts +1 -105
- package/dist/lib/server/envelope-allowlist.js +3 -79
- package/dist/lib/server/envelope-allowlist.mjs +1 -71
- package/dist/lib/server/errors.d.mts +1 -186
- package/dist/lib/server/errors.d.ts +1 -186
- package/dist/lib/server/errors.js +3 -98
- package/dist/lib/server/errors.mjs +1 -94
- package/dist/lib/server/index.d.mts +1 -1
- package/dist/lib/server/index.d.ts +1 -1
- package/dist/lib/server/mcp-modern-server.js +21 -4
- package/dist/lib/server/mcp-modern-server.mjs +21 -4
- package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
- package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
- package/dist/lib/server/media-buy-action-resolver.js +10 -1
- package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
- package/dist/lib/server/media-buy-helpers.d.mts +1 -47
- package/dist/lib/server/media-buy-helpers.d.ts +1 -47
- package/dist/lib/server/media-buy-helpers.js +3 -23
- package/dist/lib/server/media-buy-helpers.mjs +1 -18
- package/dist/lib/server/pick-safe-details.d.mts +1 -89
- package/dist/lib/server/pick-safe-details.d.ts +1 -89
- package/dist/lib/server/pick-safe-details.js +3 -61
- package/dist/lib/server/pick-safe-details.mjs +1 -56
- package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.js +3 -190
- package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
- package/dist/lib/server/targeting-helpers.d.mts +1 -123
- package/dist/lib/server/targeting-helpers.d.ts +1 -123
- package/dist/lib/server/targeting-helpers.js +3 -393
- package/dist/lib/server/targeting-helpers.mjs +1 -370
- package/dist/lib/server/test-controller.js +7 -3
- package/dist/lib/server/test-controller.mjs +7 -3
- package/dist/lib/storage/memory-ledger.js +219 -1
- package/dist/lib/storage/memory-ledger.mjs +223 -1
- package/dist/lib/testing/client.js +26 -5
- package/dist/lib/testing/client.mjs +24 -5
- package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
- package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
- package/dist/lib/testing/comply-controller.js +7 -2
- package/dist/lib/testing/comply-controller.mjs +7 -2
- package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
- package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
- package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
- package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
- package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
- package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
- package/dist/lib/testing/storyboard/runner.js +4 -4
- package/dist/lib/testing/storyboard/runner.mjs +4 -4
- package/dist/lib/testing/storyboard/task-map.js +4 -1
- package/dist/lib/testing/storyboard/task-map.mjs +4 -1
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/utils/adcp-error-response.d.mts +196 -0
- package/dist/lib/utils/adcp-error-response.d.ts +196 -0
- package/dist/lib/utils/adcp-error-response.js +118 -0
- package/dist/lib/utils/adcp-error-response.mjs +95 -0
- package/dist/lib/utils/buyer-retry-policy.js +2 -2
- package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
- package/dist/lib/utils/capabilities.d.mts +6 -0
- package/dist/lib/utils/capabilities.d.ts +6 -0
- package/dist/lib/utils/capabilities.js +6 -2
- package/dist/lib/utils/capabilities.mjs +6 -2
- package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
- package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
- package/dist/lib/utils/envelope-allowlist.js +98 -0
- package/dist/lib/utils/envelope-allowlist.mjs +71 -0
- package/dist/lib/utils/pick-safe-details.d.mts +89 -0
- package/dist/lib/utils/pick-safe-details.d.ts +89 -0
- package/dist/lib/utils/pick-safe-details.js +80 -0
- package/dist/lib/utils/pick-safe-details.mjs +56 -0
- package/dist/lib/v2/projection/augment-response.d.mts +4 -0
- package/dist/lib/v2/projection/augment-response.d.ts +4 -0
- package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
- package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
- package/dist/lib/v2/projection/creative-delivery.js +20 -4
- package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
- package/dist/lib/v2/projection/index.d.mts +2 -2
- package/dist/lib/v2/projection/index.d.ts +2 -2
- package/dist/lib/v2/projection/index.js +4 -0
- package/dist/lib/v2/projection/index.mjs +5 -1
- package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.js +14 -0
- package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
- package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
- package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
- package/dist/lib/v2/projection/legacy-routes.js +2 -1
- package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
- package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.js +18 -11
- package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
- package/dist/lib/version.d.mts +3 -3
- package/dist/lib/version.d.ts +3 -3
- package/dist/lib/version.js +3 -3
- package/dist/lib/version.mjs +3 -3
- package/docs/TYPE-SUMMARY.md +2 -2
- package/docs/guides/CREATIVE-DELIVERY.md +12 -0
- package/docs/guides/REPORTING-LEDGER.md +121 -0
- package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
- package/docs/llms.txt +2 -2
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-16-to-17.md +149 -0
- package/docs/migration-reporting-storage-package.md +10 -0
- 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';
|