Skip to content

fix: restore closed-schema guarantees under AdCP 3.3.0-beta.6 - #3705

Merged
bokelley merged 1 commit into
mainfrom
fix/beta6-closed-schema-guarantees
Nov 14, 2026
Merged

bokelley merged 1 commit into
mainfrom
fix/beta6-closed-schema-guarantees

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Summary

Follow-up to the AdCP 3.3.0-beta.6 adoption (#3703). Beta.6 opened schemas the SDK had relied on to keep undeclared data out of responses, stored evidence and webhook payloads (adcontextprotocol/adcp#8866). #3703 refused the known dangerous members by name. This PR restores the closed-schema guarantees in full. It covers the items the #3703 review stacks split out.

  • Declared-member projection. New projectToDeclaredMembers (internal, built on the version-projection $ref and union machinery) strips every member a schema does not declare, at any depth. It fails closed on an unresolved $ref. It keeps an object's undeclared contents only when a schema explicitly types that object as a free-form map, as ext is. It is applied after validation to:
    • list_accounts/sync_accounts identity objects;
    • reporting delivery states;
    • notification_configs, which also newly refuse a retained webhook_secret/authentication.signing_secret, as the other projections already did.
  • Managed reporting delivery (@adcp/reporting-storage). assertMaterializationOutcome refuses adapter evidence with undeclared members, through the new undeclaredReportingMaterializationMembers on @adcp/sdk/reporting/ledger. Its invalid-evidence message no longer quotes Zod messages, which can echo adapter values.
  • Notifications.
    • Each payload is validated against its webhook schema. The runtime refuses only not-exclusion failures, at any depth and including conditional ones: access_token on reporting.delivery_ready, setup.url on account.status_changed, staged_update on creative.status_changed. Partial payloads still emit.
    • It fails closed if a mapped schema can't load.
    • proposal.offered is identifiers-only.
    • A test cross-checks the type-to-schema map against every webhook schema in the pinned bundle.
  • Reporting subscriptions. sync_principal refused only a scope with more than one key, so a scope whose only key is an unknown selector passed, and the coverage engine treated it as all authorized accounts. Ingest now refuses it. The engine also requires an explicit all_authorized_accounts: true before covering every account.
  • Bounded walks.
    • exceedsJsonDepth is iterative and DAG-aware: a deep chain can't hide behind shallow aliases, and cycles count as too deep.
    • The credential scanner records a <too-deep> hit instead of overflowing the stack, and scrubExtensions then drops the ext/context it couldn't inspect.
    • The account projections fail with a typed error past 256 levels.
    • Reporting-status ingest omits diagnostics whose payload-derived pointer contains C0/C1 controls or U+2028/U+2029.

Changeset: minor for @adcp/sdk and @adcp/reporting-storage. One behavior change versus 17.0.0-beta.24: undeclared members that used to pass through these projections are now dropped (identity, delivery states, notification configs) or refused (managed evidence). The 16→17 migration note is updated.

Security review (REVIEW-STACKS)

Reviews run

  • Claude security-reviewer subagent on the full diff.
  • scripts/codex-review.sh --persona security and --persona code, with the diff piped on stdin. codex's sandbox can't run shell on this host, so this was a static review of the diff.

Convergence

  • Both codex personas flagged that the webhook exclusions failed open when a mapped schema couldn't load. Fixed: the runtime now throws, and the cross-check test requires every mapped schema to compile.
  • Codex code and the Claude reviewer both noted that the depth check's global seen set underestimates depth on shared subtrees. Fixed: it now tracks the greatest depth per node, with a regression test using a long chain behind shallow aliases.

Fixed from the Claude review (no High findings)

  • M1, a regression: the scanner's depth bound left a credential nested deeper than 256 levels unstripped by scrubExtensions. Now the uninspectable container is dropped.
  • M2: the hand-derived not list missed nested and conditional exclusions, and creative.status_changed. Replaced by validator-based not enforcement plus the complete, cross-checked map.
  • M3: notification_configs depended on closure. It is now projected the same way as the other account records.
  • L4: fail-open paths in the projection (unresolved $ref; undeclaring non-object schemas).
  • L5: the docs wrongly said to use a declared ext. None of these schemas declares one, and the docs now say so.
  • L6: C1 controls and U+2028/U+2029.
  • L7: the Zod message echo.

Not changed, with reasons

  • Codex security, mitigated High: it asked for an engine-level regression test with a persisted unknown selector. Ingest now refuses such a scope, so the test would have to bypass ingest validation in the store. The engine's in-scope set comes from reportingSubscriptionScopeIncludesV1, which already has an unknown-selector test from feat: adopt AdCP 3.3.0-beta.6 #3703, and membershipOf now agrees with it.
  • Codex security, partial High: declared free-form maps (ext) keep their contents by design and stay covered by credential scanning.
  • Codex security, Low: there is no breadth or byte limit on account projections. That's out of scope here.
  • Claude, L5 tail: managed delivery records DELIVERY_FAILED without the reason because the runtime has no logging hook. Adding one is a separate change.

Test plan

  • tsc --noEmit -p tsconfig.lib.json, npm run typecheck:reporting-storage, npm run build:lib
  • Affected SDK suites, including the new schema-declared-members test and the runtime, projection, wire-safe, credential-policy, ingest and principal-subscription cases
  • @adcp/reporting-storage suite
  • SDK slow lane (npm run test:node:slow), run before the review fixes; CI reruns it
  • CI

🤖 Generated with Claude Code

AdCP 3.3.0-beta.6 opened schemas (adcontextprotocol/adcp#8866) that the SDK
relied on to keep undeclared data out of responses, stored evidence and
webhook payloads.

- Project account identity objects, reporting delivery states and
  notification_configs to their declared members; refuse retained secrets.
- Refuse undeclared managed-delivery evidence members in reporting-storage
  (new undeclaredReportingMaterializationMembers on reporting/ledger).
- Enforce webhook schema `not` exclusions at any depth, fail closed when a
  mapped schema is unavailable, and make proposal.offered identifiers-only.
- Refuse an unknown single reporting-subscription scope selector; the engine
  covers every account only for an explicit all_authorized_accounts.
- Bound credential scanning and projections by depth (DAG-aware), drop an
  uninspectable ext/context in scrubExtensions, and drop ingest diagnostics
  with control characters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — clean review, no blocking findings.

This PR restores the closed-schema guarantees that beta.6 opened (adcp#8866). Reviewer verified the two largest surfaces:

  • keepDeclared/projectToDeclaredMembers in schema-projection.ts: free-form-map detection correctly keeps declared ext maps while dropping undeclared members (L172), fail-closed on unresolved $ref (L148), RangeError at depth > MAX_DEPTH=64.
  • assertWebhookExclusions in notification runtime (L536-572): loader honors allErrors in its cache key (schema-loader.ts:1343), so not-exclusions are reliably caught.

engine.ts memberNow now requires explicit all_authorized_accounts === true, matched by the validateReportingSubscription selector-allowlist fix; both tested. exceedsJsonDepth is iteratively bounded with cycle/alias handling. Credential-scan and scrubExtensions fail closed on too-deep subtrees. Changeset present (minor for both packages, correct under 17 beta pre-mode). Strong test coverage across every new branch.

The sole non-blocking note (depth-guard mismatch at 256 vs RangeError at 64) is not reachable for the bounded structured objects in scope — a low/speculative concern, not a finding.

Decision path: no critical/high findings; gated_paths false; high_risk false; no medium findings; author not on a no-auto-approve team; fewer than three mediums → row 9 approve. (review_decision REVIEW_REQUIRED is informational only since gated_paths is false.)

@bokelley
bokelley merged commit 3408d45 into main Nov 14, 2026
45 checks passed
@bokelley
bokelley deleted the fix/beta6-closed-schema-guarantees branch November 14, 2026 01:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant