fix: move SVCB key numbers to RFC 9460 Private Use range (v0.9.0) (#38)

iracic82 · web-flow · commit 7e5e38de50c7 · 2026-02-24T11:43:51.000+01:00
All custom SvcParamKeys migrated from the Expert Review range
(65001-65010) to the Private Use range (65280-65534) per RFC 9460
Section 14.3:

  cap=key65400, cap-sha256=key65401, bap=key65402,
  policy=key65403, realm=key65404, sig=key65405

The old numbers (65001-65010) required IANA registration. The new
numbers (65400-65405) are in the Private Use range and free to use.

Verified end-to-end against live Route53 and NIOS backends.

BREAKING CHANGE: Existing DNS records using old key numbers will
need re-publishing.

Signed-off-by: Igor Racic &lt;iracic82@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to DNS-AID will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-02-24
+
+### Changed
+- **SVCB key numbers moved to RFC 9460 Private Use range** — All custom SvcParamKeys migrated from the Expert Review range (65001–65010) to the Private Use range (65280–65534) per RFC 9460 Section 14.3. New mapping: cap=key65400, cap-sha256=key65401, bap=key65402, policy=key65403, realm=key65404, sig=key65405. **Breaking:** existing DNS records using the old key numbers will need re-publishing.
+
 ## [0.8.0] - 2026-02-21
 
 ### Added
@@ -15,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - **BANDAID → DNS-AID rename** — All references to "BANDAID" and `bandaid_` updated to "DNS-AID" and `dnsaid_` across source, tests, docs, and metadata files. IETF draft reference updated from `draft-mozleywilliams-dnsop-bandaid-02` to `draft-mozleywilliams-dnsop-dnsaid-01`
-- **`bap` SvcParamKey number** — Changed from `key65003` to `key65010` to match IETF draft Section 4.4.3 example. **Breaking:** existing DNS records with `key65003` for bap will need re-publishing
+- **`bap` SvcParamKey number** — Changed from `key65003` to `key65010` to match IETF draft Section 4.4.3 example. **Breaking:** existing DNS records with `key65003` for bap will need re-publishing (further updated to `key65402` in v0.9.0)
 
 ## [0.7.3] - 2026-02-19
 
@@ -150,15 +155,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Experimental Models Documentation** — Marked `agent_metadata` and `capability_model` modules as experimental with status docstrings
 
 ### Fixed
-- **Route53 SVCB custom params** — Route53 rejects private-use SvcParamKeys (`key65001`–`key65006`). The Route53 backend now demotes custom DNS-AID params to TXT records with `dnsaid_` prefix, keeping the publish working without data loss
+- **Route53 SVCB custom params** — Route53 rejects private-use SvcParamKeys (`key65400`–`key65405`). The Route53 backend now demotes custom DNS-AID params to TXT records with `dnsaid_` prefix, keeping the publish working without data loss
 - **Cloudflare SVCB custom params** — Same demotion applied to the Cloudflare backend
 - **CLI `--backend` help text** — Now lists all five backends (route53, cloudflare, infoblox, ddns, mock) instead of just "route53, mock"
 - **SECURITY.md contact** — Updated from placeholder LF mailing list to interim maintainer email
 - **Bandit config** — Migrated from `.bandit` INI to `pyproject.toml` `[tool.bandit]` for newer bandit compatibility
 - **CLI ANSI escape codes** — Stripped Rich/Typer ANSI codes in test assertions for Python 3.13 compatibility
 
 ### Notes
-- BIND/DDNS backends natively support custom SVCB params (`key65001`–`key65006`) — no demotion needed
+- BIND/DDNS backends natively support custom SVCB params (`key65400`–`key65405`) — no demotion needed
 - DNSSEC enforcement defaults to `False` (backwards compatible)
 - DANE cert matching defaults to `False` (advisory TLSA existence check remains the default)
 
diff --git a/README.md b/README.md
@@ -343,7 +343,7 @@ _booking._mcp._agents.example.com. SVCB 1 mcp.example.com. alpn="mcp" port=443 \
 | `policy` | URI to agent policy document |
 | `realm` | Multi-tenant scope identifier |
 
-> **Note:** Route 53 and Cloudflare do not support private-use SVCB SvcParamKeys (`key65001`–`key65006`).
+> **Note:** Route 53 and Cloudflare do not support private-use SVCB SvcParamKeys (`key65400`–`key65405`).
 > DNS-AID automatically demotes these parameters to TXT records with a `dnsaid_` prefix (e.g.,
 > `dnsaid_realm=production`), preserving all metadata without data loss. BIND/DDNS (RFC 2136)
 > backends natively support custom SVCB params — no demotion needed.
@@ -793,7 +793,7 @@ Infoblox NIOS is the on-premise DDI platform with WAPI (Web API). DNS-AID create
 
 #### NIOS DNS-AID Compliance
 
-NIOS WAPI supports ServiceMode SVCB records (priority > 0) with full SVC parameters, including custom DNS-AID keys natively via `key65001`–`key65006`.
+NIOS WAPI supports ServiceMode SVCB records (priority > 0) with full SVC parameters, including custom DNS-AID keys natively via `key65400`–`key65405`.
 
 ### DDNS Setup (RFC 2136)
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -70,7 +70,7 @@ All outbound HTTP fetches (capability document retrieval, A2A agent card fetches
 
 ### Capability Document Integrity (cap_sha256)
 
-When a `cap-sha256` (key65002) value is present in an SVCB record, DNS-AID verifies the integrity of the fetched capability document:
+When a `cap-sha256` (key65401) value is present in an SVCB record, DNS-AID verifies the integrity of the fetched capability document:
 
 - The SHA-256 digest of the fetched document body is computed and base64url-encoded (unpadded).
 - The computed digest is compared to the `cap-sha256` value from DNS.
@@ -79,18 +79,18 @@ When a `cap-sha256` (key65002) value is present in an SVCB record, DNS-AID verif
 
 ### SVCB Custom Parameter Keys
 
-DNS-AID uses SVCB SvcParamKeys in the **private-use range** (65001–65534) as defined by RFC 9460:
+DNS-AID uses SVCB SvcParamKeys in the **RFC 9460 Private Use range** (65280–65534):
 
 | Key     | Number   | Purpose                          |
 | ------- | -------- | -------------------------------- |
-| cap     | key65001 | Capability document URI          |
-| cap-sha256 | key65002 | Capability document SHA-256 hash |
-| bap     | key65010 | DNS-AID Application Protocols    |
-| policy  | key65004 | Policy document URI              |
-| realm   | key65005 | Administrative realm             |
-| sig     | key65006 | JWS signature                    |
-
-These key numbers are in the private-use range pending IANA registration through the IETF draft process. The numeric form (`key65001`) is the default wire format; the string form (`cap`) can be enabled via the `DNS_AID_SVCB_STRING_KEYS` environment variable for human-readable debugging.
+| cap     | key65400 | Capability document URI          |
+| cap-sha256 | key65401 | Capability document SHA-256 hash |
+| bap     | key65402 | DNS-AID Application Protocols    |
+| policy  | key65403 | Policy document URI              |
+| realm   | key65404 | Administrative realm             |
+| sig     | key65405 | JWS signature                    |
+
+These key numbers are in the Private Use range pending IANA registration through the IETF draft process. The numeric form (`key65400`) is the default wire format; the string form (`cap`) can be enabled via the `DNS_AID_SVCB_STRING_KEYS` environment variable for human-readable debugging.
 
 ## Input Validation
 
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -508,7 +508,7 @@ backend = InfobloxNIOSBackend(
 | `NIOS_WAPI_VERSION` | No | `2.13.7` | WAPI version |
 | `NIOS_VERIFY_SSL` | No | `false` | Verify TLS certificate |
 
-**DNS-AID Compliance**: NIOS WAPI supports ServiceMode SVCB records (priority > 0) with full SVC parameters including custom DNS-AID keys (`key65001`–`key65006`). Fully compliant with the DNS-AID draft.
+**DNS-AID Compliance**: NIOS WAPI supports ServiceMode SVCB records (priority > 0) with full SVC parameters including custom DNS-AID keys (`key65400`–`key65405`). Fully compliant with the DNS-AID draft.
 
 ### DDNSBackend
 
diff --git a/docs/demo-guide.md b/docs/demo-guide.md
@@ -727,7 +727,7 @@ Capabilities are resolved with the following priority, aligned with the DNS-AID
 │              Capability Resolution Priority                      │
 │                                                                 │
 │  1. SVCB cap URI    ──►  GET /cap/{agent}  ──►  Capability JSON │
-│     (key65001)           (fetch document)       (authoritative) │
+│     (key65400)           (fetch document)       (authoritative) │
 │         │                                                       │
 │         ▼ (fallback if cap URI absent or fetch fails)           │
 │  2. TXT Record      ──►  "capabilities=travel,booking"          │
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -380,7 +380,7 @@ dns-aid delete \
 
 ### NIOS DNS-AID Compliance
 
-NIOS WAPI supports ServiceMode SVCB records (priority > 0) with full SVC parameters, including custom DNS-AID keys natively via `key65001`–`key65006`. This makes it fully compliant with the DNS-AID draft.
+NIOS WAPI supports ServiceMode SVCB records (priority > 0) with full SVC parameters, including custom DNS-AID keys natively via `key65400`–`key65405`. This makes it fully compliant with the DNS-AID draft.
 
 ## DDNS Setup (RFC 2136)
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dns-aid"
-version = "0.8.0"
+version = "0.9.0"
 description = "DNS-based Agent Identification and Discovery - Reference Implementation"
 readme = "README.md"
 license = "Apache-2.0"
diff --git a/src/dns_aid/__init__.py b/src/dns_aid/__init__.py
@@ -46,7 +46,7 @@
 # Alias for convenience
 delete = unpublish
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 __all__ = [
     # Core functions (Tier 0)
     "publish",
diff --git a/src/dns_aid/backends/cloudflare.py b/src/dns_aid/backends/cloudflare.py
@@ -25,7 +25,7 @@
 logger = structlog.get_logger(__name__)
 
 # Standard SVCB SvcParamKeys that managed DNS providers accept (RFC 9460).
-# Cloudflare rejects private-use keys (key65001–key65534) the same way
+# Cloudflare rejects private-use keys (key65280–key65534) the same way
 # Route53 does.  Custom DNS-AID params are demoted to TXT automatically.
 _CLOUDFLARE_SVCB_KEYS = frozenset(
     {
@@ -354,7 +354,7 @@ async def publish_agent(self, agent: AgentRecord) -> list[str]:
         Publish an agent to DNS, demoting unsupported SVCB params to TXT.
 
         Cloudflare only accepts standard RFC 9460 SvcParamKeys. Custom DNS-AID
-        params (key65001–key65006) are automatically moved to the TXT record.
+        params (key65400–key65405) are automatically moved to the TXT record.
         """
         records: list[str] = []
         zone = agent.domain
diff --git a/src/dns_aid/backends/infoblox/nios.py b/src/dns_aid/backends/infoblox/nios.py
@@ -50,12 +50,12 @@ class InfobloxNIOSBackend(DNSBackend):
     # NIOS only accepts registered SVC keys or keyNNNNN numeric keys.
     # Map draft custom names to private-use keyNNNNN aliases for compatibility.
     _CUSTOM_PARAM_TO_NUMERIC_KEY = {
-        "cap": "key65001",
-        "cap-sha256": "key65002",
-        "bap": "key65010",
-        "policy": "key65004",
-        "realm": "key65005",
-        "sig": "key65006",
+        "cap": "key65400",
+        "cap-sha256": "key65401",
+        "bap": "key65402",
+        "policy": "key65403",
+        "realm": "key65404",
+        "sig": "key65405",
     }
     _NUMERIC_KEY_TO_CUSTOM_PARAM = {
         value: key for key, value in _CUSTOM_PARAM_TO_NUMERIC_KEY.items()
diff --git a/src/dns_aid/backends/route53.py b/src/dns_aid/backends/route53.py
@@ -26,7 +26,7 @@
 logger = structlog.get_logger(__name__)
 
 # Standard SVCB SvcParamKeys that Route53 accepts (RFC 9460).
-# Route53 rejects private-use keys (key65001–key65534) with
+# Route53 rejects private-use keys (key65280–key65534) with
 # "SVCB does not support undefined parameters."
 # When publishing, custom DNS-AID params are automatically demoted
 # to TXT records so the publish succeeds.
@@ -297,7 +297,7 @@ async def publish_agent(self, agent: AgentRecord) -> list[str]:
         Publish an agent to DNS, demoting unsupported SVCB params to TXT.
 
         Route53 only accepts standard RFC 9460 SvcParamKeys. Custom DNS-AID
-        params (key65001–key65006) are automatically moved to the TXT record
+        params (key65400–key65405) are automatically moved to the TXT record
         so the publish succeeds without data loss.
         """
         records: list[str] = []
diff --git a/src/dns_aid/core/discoverer.py b/src/dns_aid/core/discoverer.py
@@ -330,7 +330,7 @@ def _parse_svcb_custom_params(svcb_text: str) -> dict[str, str]:
 
     Accepts both human-readable string names and RFC 9460 keyNNNNN format:
         String form: cap="https://..." bap="mcp,a2a" realm="demo"
-        Numeric form: key65001="https://..." key65010="mcp,a2a" key65005="demo"
+        Numeric form: key65400="https://..." key65402="mcp,a2a" key65404="demo"
 
     Args:
         svcb_text: String representation of an SVCB rdata.
diff --git a/src/dns_aid/core/models.py b/src/dns_aid/core/models.py
@@ -17,15 +17,15 @@
 from pydantic import BaseModel, Field, field_validator
 
 # DNS-AID custom SVCB param key mapping (IETF draft-01, Section 4.4.3)
-# These are provisional private-use key numbers in the range 65001-65534.
+# These use the RFC 9460 Private Use range (65280-65534).
 # Once IANA assigns official SvcParamKey numbers, update these values.
 DNS_AID_KEY_MAP: dict[str, str] = {
-    "cap": "key65001",
-    "cap-sha256": "key65002",
-    "bap": "key65010",
-    "policy": "key65004",
-    "realm": "key65005",
-    "sig": "key65006",
+    "cap": "key65400",
+    "cap-sha256": "key65401",
+    "bap": "key65402",
+    "policy": "key65403",
+    "realm": "key65404",
+    "sig": "key65405",
 }
 
 DNS_AID_KEY_MAP_REVERSE: dict[str, str] = {v: k for k, v in DNS_AID_KEY_MAP.items()}
@@ -134,7 +134,7 @@ class AgentRecord(BaseModel):
     #
     # DNS-AID draft-01 gap (deferred — keyNNNNN encoding):
     #     The draft specifies that unregistered SVCB params MUST use numeric
-    #     keyNNNNN presentation form (e.g., key65001="cap=..." instead of
+    #     keyNNNNN presentation form (e.g., key65400="cap=..." instead of
     #     cap="...") until IANA assigns official SvcParamKey numbers.
     #     We use human-readable string names for now because:
     #     (a) IANA registration has not occurred yet,
@@ -145,7 +145,7 @@ class AgentRecord(BaseModel):
     #
     # DNS-AID draft-01 gap (deferred — mandatory list):
     #     The draft says clients that require custom params MUST verify their
-    #     presence via the `mandatory` key (e.g., mandatory=alpn,port,key65001).
+    #     presence via the `mandatory` key (e.g., mandatory=alpn,port,key65400).
     #     Per RFC 9460, clients that don't understand a mandatory key MUST skip
     #     the record. We currently only set mandatory=alpn,port to avoid breaking
     #     non-DNS-AID-aware clients. Once keyNNNNN encoding is adopted, we should
diff --git a/tests/unit/test_cloudflare_backend.py b/tests/unit/test_cloudflare_backend.py
@@ -670,7 +670,7 @@ class TestCloudflarePublishAgentParamDemotion:
 
     @pytest.mark.asyncio
     async def test_publish_strips_custom_svcb_params(self):
-        """Custom DNS-AID params (key65001+) must be demoted to TXT."""
+        """Custom DNS-AID params (key65400+) must be demoted to TXT."""
         from dns_aid.core.models import AgentRecord, Protocol
 
         agent = AgentRecord(
diff --git a/tests/unit/test_infoblox_nios_backend.py b/tests/unit/test_infoblox_nios_backend.py
@@ -167,26 +167,26 @@ def test_svc_parameters_conversion(self) -> None:
         as_map = {item["svc_key"]: item for item in converted}
         assert as_map["alpn"]["svc_value"] == ["h2", "h3"]
         assert as_map["alpn"]["mandatory"] is True
-        assert as_map["key65010"]["svc_value"] == ["mcp/1", "a2a/1"]
+        assert as_map["key65402"]["svc_value"] == ["mcp/1", "a2a/1"]
         assert as_map["port"]["svc_value"] == ["443"]
-        assert as_map["key65001"]["mandatory"] is True
-        assert as_map["key65006"]["svc_value"] == ["abc123"]
+        assert as_map["key65400"]["mandatory"] is True
+        assert as_map["key65405"]["svc_value"] == ["abc123"]
 
     def test_svc_parameters_preserves_numeric_keys(self) -> None:
         converted = InfobloxNIOSBackend._svc_parameters_from_params(
-            {"mandatory": "key65010,port", "key65010": "mcp/1,a2a/1", "port": "443"}
+            {"mandatory": "key65402,port", "key65402": "mcp/1,a2a/1", "port": "443"}
         )
         as_map = {item["svc_key"]: item for item in converted}
 
-        assert as_map["key65010"]["mandatory"] is True
-        assert as_map["key65010"]["svc_value"] == ["mcp/1", "a2a/1"]
+        assert as_map["key65402"]["mandatory"] is True
+        assert as_map["key65402"]["svc_value"] == ["mcp/1", "a2a/1"]
         assert as_map["port"]["mandatory"] is True
 
     def test_format_svc_parameters_for_value(self) -> None:
         svc_params = [
             {"svc_key": "alpn", "svc_value": ["mcp"], "mandatory": True},
             {"svc_key": "port", "svc_value": ["443"], "mandatory": True},
-            {"svc_key": "key65005", "svc_value": ["prod"], "mandatory": False},
+            {"svc_key": "key65404", "svc_value": ["prod"], "mandatory": False},
         ]
         result = InfobloxNIOSBackend._format_svc_parameters_for_value(svc_params)
         assert 'mandatory="alpn,port"' in result
@@ -251,7 +251,7 @@ async def fake_request(
         assert payload["ttl"] == 900
         assert payload["use_ttl"] is True
         assert payload["view"] == "default"
-        assert any(param["svc_key"] == "key65005" for param in payload["svc_parameters"])
+        assert any(param["svc_key"] == "key65404" for param in payload["svc_parameters"])
 
     async def test_create_svcb_record_update(
         self, backend: InfobloxNIOSBackend, monkeypatch: pytest.MonkeyPatch
@@ -517,7 +517,7 @@ async def fake_request(
                             {"svc_key": "alpn", "svc_value": ["mcp"], "mandatory": True},
                             {"svc_key": "port", "svc_value": ["443"], "mandatory": True},
                             {
-                                "svc_key": "key65005",
+                                "svc_key": "key65404",
                                 "svc_value": ["prod"],
                                 "mandatory": False,
                             },
diff --git a/tests/unit/test_jws.py b/tests/unit/test_jws.py
@@ -482,9 +482,9 @@ def test_agent_record_sig_in_svcb_params(self):
         )
 
         params = agent.to_svcb_params()
-        # Default: keyNNNNN format (key65006 = sig)
-        assert "key65006" in params
-        assert params["key65006"].startswith("eyJ")
+        # Default: keyNNNNN format (key65405 = sig)
+        assert "key65405" in params
+        assert params["key65405"].startswith("eyJ")
 
     def test_agent_record_no_sig_when_none(self):
         """Test that sig is not in SVCB params when None."""
diff --git a/tests/unit/test_models.py b/tests/unit/test_models.py
@@ -129,11 +129,11 @@ def test_svcb_params_with_dnsaid_custom_params_keynnnnn(self):
         params = agent.to_svcb_params()
 
         # Default: keyNNNNN format per RFC 9460
-        assert params["key65001"] == "https://mcp.example.com/.well-known/agent-cap.json"
-        assert params["key65002"] == "abc123base64url"
-        assert params["key65010"] == "mcp/1,a2a/1"
-        assert params["key65004"] == "https://example.com/agent-policy"
-        assert params["key65005"] == "production"
+        assert params["key65400"] == "https://mcp.example.com/.well-known/agent-cap.json"
+        assert params["key65401"] == "abc123base64url"
+        assert params["key65402"] == "mcp/1,a2a/1"
+        assert params["key65403"] == "https://example.com/agent-policy"
+        assert params["key65404"] == "production"
         # Standard params still present
         assert params["alpn"] == "mcp"
         assert params["port"] == "443"
@@ -199,11 +199,11 @@ def test_svcb_params_partial_dnsaid_params(self):
         params = agent.to_svcb_params()
 
         # Default: keyNNNNN format
-        assert params["key65001"] == "https://mcp.example.com/.well-known/agent-cap.json"
-        assert params["key65005"] == "demo"
-        assert "key65002" not in params
-        assert "key65010" not in params
-        assert "key65004" not in params
+        assert params["key65400"] == "https://mcp.example.com/.well-known/agent-cap.json"
+        assert params["key65404"] == "demo"
+        assert "key65401" not in params
+        assert "key65402" not in params
+        assert "key65403" not in params
 
     def test_svcb_params_cap_sha256_without_cap_uri(self):
         """Test cap-sha256 can be set independently (unlikely but valid)."""
@@ -217,8 +217,8 @@ def test_svcb_params_cap_sha256_without_cap_uri(self):
 
         params = agent.to_svcb_params()
 
-        assert params["key65002"] == "dGVzdGhhc2g"
-        assert "key65001" not in params
+        assert params["key65401"] == "dGVzdGhhc2g"
+        assert "key65400" not in params
 
     def test_txt_values(self):
         """Test TXT record values generation."""
diff --git a/tests/unit/test_publisher.py b/tests/unit/test_publisher.py
diff --git a/tests/unit/test_route53_backend.py b/tests/unit/test_route53_backend.py
diff --git a/uv.lock b/uv.lock
