feat(v2): write-side helpers + format_schema $ref sandboxing

[bokelley]

Summary

Two adopter-facing additions on top of 7.10's V2 projection layer (PR #1882):

1. Write-side helpers — formatIdsFromOptions / formatIdsForCapability

Bridges the spec gap documented at adcontextprotocol/adcp#4842 — PackageRequest at 3.1-beta still carries only format_ids[] (no capability_id v2 path). V2 buyers reading format_options[] from getProducts need to translate their chosen declaration back through v1_format_ref[] to write create_media_buy. These helpers are the canonical place that bridge lives so adopters don't inline decl.v1_format_ref pluckers everywhere.

import { formatIdsFromOptions } from '@adcp/sdk/v2/projection';

const chosen = product.format_options.find(o => o.format_kind === 'image');
await agent.createMediaBuy({
  packages: [{
    package_id: 'pkg-1',
    product_id: product.product_id,
    pricing_option_id: product.pricing_options[0].pricing_option_id,
    format_ids: formatIdsFromOptions(chosen),
    budget: { currency: 'USD', total: 5000 },
  }],
});

Returns [] when the declaration has no v1 form (canonical_formats_only: true or inherently-v2 canonical). Helpers deprecate once adcontextprotocol/adcp#4842 lands.

2. resolveSchemaRefs — $ref sandboxing + DoS bounds

Implements the spec's normative $ref rules from product-format-declaration.json#format_schema:

• Intra-document #/...: resolved against parent doc (RFC 6901). Cycles trip the depth limit.
• Same-origin: allowed; RFC 3986 §6 origin normalization.
• AAO mirror host (mirror.adcontextprotocol.org): allowed.
• file://: rejected unconditionally.
• Cross-origin: rejected with a diagnostic naming both origins.
• Bounds: depth ≤ 8, count ≤ 256 (spec ceilings; tunable).

External fetches go through ssrfSafeFetch (HTTPS + SSRF + 1 MiB cap + 5 s timeout). Per-\$ref digest verification is opt-in via custom fetchExternal — parent format_schema.uri@digest is the trust anchor; same-origin / mirror refs inherit trust.

import { fetchFormatSchema, resolveSchemaRefs } from '@adcp/sdk/v2/format-schema';

const { schema, ref } = await fetchFormatSchema(formatSchemaRef);
const { schema: resolved } = await resolveSchemaRefs(schema, ref.uri);
// Feed `resolved` to Ajv — every \$ref already inlined.

Also exports DEFAULT_MAX_KEYWORDS (10_000) and DEFAULT_VALIDATION_BUDGET_MS (250) constants for the future Ajv-wiring layer (manifest validator) — the sandboxer itself doesn't enforce them.

Tests

22 new (8 write-side + 14 sandbox), all passing. 32 in the broader format-schema test set pass.

Out of scope (still deferred)

• Manifest-layer pixel_tracker v1↔v2 translation (with sync_creatives wiring).
• Schema-compile DoS enforcement (re2 regex, allOf expansion) — applied at the Ajv compile step in the manifest validator.
• Outbound v2→v1 projection for create_media_buy requests — waiting on PackageRequest lacks v2 capability_id path — V2 mental model breaks at create_media_buy boundary adcp#4842.

Test plan

• CI typecheck + lint
• CI full test suite
• Changeset check (minor)
• Manual: `resolveSchemaRefs` against a real publisher format_schema with one $ref (post-merge)

🤖 Generated with Claude Code

[bokelley]

Expert review round complete. Ran 4 agents in parallel (security, ad-tech-protocol, code-reviewer-deep, dx-expert) + CI in parallel. CI was green on the original push; expert review surfaced five convergent findings plus polish items.

Pushed 51a51a4f addressing all of them.

Ship-blockers fixed

1. Sibling-merge flipped safety. { $ref, additionalProperties: true } silently overrode the referent's additionalProperties: false. Now: sibling allowlist limited to annotation-only keys (description / title / $comment / examples / default / deprecated / readOnly / writeOnly / $schema); constraint siblings throw invalid_ref. Merge spread also reversed defensively (referent wins on collision).
2. http://mirror... accepted on the mirror branch. Spec requires https. Dropped.
3. JSON Pointer __proto__ / constructor / prototype traversal. hasOwnProperty alone doesn't block — JSON.parse can produce own __proto__. Added FORBIDDEN_POINTER_SEGMENTS reject set.
4. Mirror domain spec inconsistency. format_schema $ref section references mirror.adcontextprotocol.org but 3.1 migrated the AAO mirror to creative.adcontextprotocol.org. Filed adcontextprotocol/adcp#4862. Interim: DEFAULT_MIRROR_HOSTS accepts both.
5. formatIdsFromOptions silently returned []. Now throws fail-closed with a diagnostic naming the capability_id/format_kind. Added tryFormatIdsFromOptions non-throwing variant for iterate-and-pick workflows.

DX polish

• @see formatIdsFromOptions on V2AugmentedProduct so LLM-driven buyer agents find the bridge.
• Expanded AgentClient.createMediaBuy JSDoc with the v2→v1 worked example.

Tests

8 new sandbox tests (constraint-sibling rejection, annotation-allowlist, https-only mirror, __proto__ rejection, dual-host default, subdomain-spoofed mirror rejected, external→intra-doc body swap). 3 new write-side tests for the new throw + try* variant. Fixture updates for the new sibling rule. 117/117 v2+projection+format-schema tests passing locally.

Will admin-merge when CI is green on this push.

[bokelley]

Acknowledged — all five blockers addressed in 51a51a4f, tests at 117/117. Standing by; no action needed from triage.

---

Generated by Claude Code

[bokelley]

Noted — standing by. No triage action taken.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01BNY6uH2CkZhq3EgyQxctrk

---

Generated by Claude Code