Clarify pushNotificationConfig.url port semantics (declare unconstrained)

[bokelley]

Background

schemas/cache/core/push-notification-config.json (line 7-11) defines url as format: \"uri\" with no port restriction. The spec is silent on whether publishers may restrict destination ports.

Why it matters

SDKs implementing the publisher side need to decide whether to enforce a port allowlist on buyer-supplied URLs as defense-in-depth against SSRF (a buyer URL like https://internal.example.com:6379/ can smuggle traffic to internal Redis on the same routable IP, even when the IP-range check passes).

If SDKs implement port allowlists by default, they reject legitimate buyers on non-standard TLS ports — Tomcat default :9443, Spring Boot default :4443, path-routed multi-tenant gateways. If they don't, the SSRF guard is weaker.

The Python SDK's foundation audit (adcp-client-python#297 review) initially defaulted to {443, 8443} — the protocol-expert review flagged this as over-restriction, since the spec doesn't constrain ports. The fix: default permissive, expose DEFAULT_ALLOWED_PORTS as opt-in operator hardening.

Proposed fix

Add a single sentence to push-notification-config.json url description:

Publishers SHOULD NOT constrain the URL's port to standard HTTPS values (443, 8443) by default — buyers may legitimately host webhook receivers on non-standard ports (:9443 Tomcat, :4443 Spring Boot, path-routed multi-tenant gateways). Operators who want a hardened destination-port allowlist as defense in depth opt in explicitly; the default URL contract is unconstrained beyond the format: uri requirement.

Optional: also note in docs/building/implementation/security.mdx#webhook-callbacks that AdCP recommends {443, 8443} for hardened deployments — see related issue.

Why now

Locks the spec position so SDKs stop diverging on this. The Python SDK exports DEFAULT_ALLOWED_PORTS = {443, 8443} as opt-in hardening (adcp.signing.DEFAULT_ALLOWED_PORTS), aligned with what the recommendation should be.

Surfaced by Python SDK foundation audit on adcp-client-python#297.

[bokelley]

Triage

Classification: Spec clarification / security guidance
Bucket(s): spec / protocol, security-sensitive
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Direction correct — permissive ports by default matches every peer spec (OpenRTB nurl, VAST tracking pixels, A2A PushNotificationConfig). But the SHOULD NOT fails the patch-eligibility test: a conformant 3.0 seller already restricting ports was conformant before; SHOULD NOT makes it non-conformant. This is minor, not patch — targets 3.1.x. Two structural concerns: (1) normative language belongs in the SSRF section of security.mdx, not in the schema description field; (2) the wire-level opt-in for "hardened mode" is undefined — no protocol field lets a seller detect buyer opt-in.
• security-reviewer: Permissive-port posture is architecturally sound given existing TLS + IP-range + no-echo-errors controls. Flagging a separate implementation gap in the outbound webhook delivery path (details withheld — security-sensitive) that should be resolved before the spec can truthfully say IP-range checks are the primary guard. Confirms normative home should be security.mdx; schema description should be a pointer only.

My take: Both experts agree on the direction but flag two items for a human call: (1) versioning — this is minor, ships in 3.1.x; (2) a related implementation concern the security-reviewer surfaced that is worth addressing independently. @bokelley, your call: (A) land as minor in 3.1.x with the SHOULD NOT consolidated into the SSRF section of security.mdx; or (B) land a non-normative guidance note in security.mdx now as --empty (docs-only), and reserve the normative SHOULD NOT for 3.1. The implementation finding should be tracked as a separate issue regardless of which path.

---

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

---

Generated by Claude Code