UQRP Protocol Specification

Overview

ResolveDB transforms DNS infrastructure into a data distribution platform. Data is encoded in DNS queries and responses, leveraging global DNS caching for sub-millisecond access.

Implementation Status

This specification describes both implemented features and planned capabilities.

For current implementation details, see the resolvedb-core source.

Explicit Parameters Design

ResolveDB uses explicit parameters for all context-dependent queries. The server never infers client identity, location, or preferences from the source IP address. This design provides predictability, privacy, cache efficiency, and auditability.

Core Principles

Benefits

Why Traditional GeoDNS Breaks

Traditional DNS-based services infer client location from source IP, causing:

1. Unpredictable results - Same query returns different data from different networks
2. Proxy/VPN breakage - Queries return data for the proxy's location, not yours
3. Cache fragmentation - ECS-scoped responses create thousands of cache entries per /24 subnet
4. Privacy leakage - Server logs reveal your approximate location
5. Testing difficulty - Can't reproduce production behavior in CI/staging

Explicit Parameter Pattern

# CORRECT: Client explicitly provides context
get.ip-8-8-8-8.geoip.v1.resolvedb.net           # GeoIP for specific IP
get.city-newyork.weather.v1.resolvedb.net       # Weather for named location
get.lat-40d7128.lon--74d0060.weather.v1.resolvedb.net  # Weather for coordinates
get.region-eu.config.hooli.v1.resolvedb.net     # EU-specific configuration

# WRONG: Implicit context (rejected or undefined behavior)
get.weather.v1.resolvedb.net                    # ← What location? Rejected!
geoip.self.v1.resolvedb.net                     # ← Rejected with FormErr

Privacy Best Practices

For applications handling sensitive data, ResolveDB supports multiple layers of protection:

Client-side encryption example:

// Encrypt before storing - server never sees plaintext
const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
const iv = crypto.getRandomValues(new Uint8Array(12));
const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, data);

// Store encrypted blob
await resolvedb.put('secrets.api-key.hooli.v1', base64(iv + encrypted));

// Retrieve and decrypt client-side
const blob = await resolvedb.get('secrets.api-key.hooli.v1');
const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: blob.iv }, key, blob.ciphertext);

Client                    DNS Resolver              ResolveDB Authoritative
   |                           |                              |
   |-- get.city-nyc.weather.v1.resolvedb.net ---------------->|
   |                           |                              |
   |<-- TXT "v=rdb1;s=ok;d={"temp":72}" ---------------------|
   |                           |                              |
   |-- (cached globally) ----->|                              |

Write Operations

Important: Write operations (put, delete) are handled via the HTTP API at api.resolvedb.io, not via DNS queries. DNS is a read-optimized protocol; writes flow through the API.

Why API for Writes?

• DNS queries are limited to 253 characters (FQDN limit)
• DNS lacks reliable delivery guarantees for mutations
• Authentication is simpler over HTTPS
• Write confirmation requires bidirectional communication

API Examples

# Create/update a resource
curl -X PUT https://api.resolvedb.io/v1/namespaces/hooli/resources/config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark", "locale": "en-US"}'

# Delete a resource
curl -X DELETE https://api.resolvedb.io/v1/namespaces/hooli/resources/config \
  -H "Authorization: Bearer <token>"

# List resources
curl https://api.resolvedb.io/v1/namespaces/hooli/resources \
  -H "Authorization: Bearer <token>"

After a write, the data is immediately available via DNS queries:

dig TXT get.settings.config.hooli.v1.resolvedb.net +short
# "v=rdb1;s=ok;t=data;e=b64;f=json;ttl=3600;d=eyJhcGlfdXJsIjoiaHR0cHM6Ly9hcGkuaG9vbGkuZGV2IiwidGltZW91dF9tcyI6NTAwMCwicmV0cnlfY291bnQiOjMsImxvZ19sZXZlbCI6ImluZm8ifQ=="
# d= is base64 (the renderer encodes any value containing `;`, `=`, or `"` to
# stay TXT-safe); it decodes to:
#   {"api_url":"https://api.hooli.dev","timeout_ms":5000,"retry_count":3,"log_level":"info"}

Namespace Architecture

Hostname Scoping Protocol (HSP)

resolvedb.<tld>                          # Root domain (.com/.net/.org/.io)
├── public.resolvedb.<tld>               # Public data services
├── user.resolvedb.<tld>                 # User-owned namespaces
├── system.resolvedb.<tld>               # System operations
└── registry.resolvedb.<tld>             # Service registry

Public Namespace (public.resolvedb.<tld>)

Globally accessible data through standardized interfaces. Supports pluggable providers including MCPs.

<query>.<parameters>.<service>.<version>.public.resolvedb.<tld>

Examples:
current.celsius.newyork.weather.v1.public.resolvedb.net
price.aapl.nasdaq.stock.v1.public.resolvedb.net
latest.headlines.tech.news.v1.public.resolvedb.net

Service Registration:

_service.weather.v1.public.resolvedb.net    TXT  "v=rdb1;type=mcp;endpoint=weather-mcp://api;schema=v1.2.0"
_caps.weather.v1.public.resolvedb.net       TXT  "methods=current,forecast;formats=json,xml;auth=none"
_schema.weather.v1.public.resolvedb.net     URI  "https://schemas.resolvedb.net/weather/v1/openapi.json"

User Namespace (user.resolvedb.<tld>)

Isolated data storage for individuals and organizations.

<data>.<collection>.<user-id>.user.resolvedb.<tld>
<data>.<app>.<org-identifier>.user.resolvedb.<tld>

Examples:
profile.settings.hooli-user.user.resolvedb.net
config.settings.prod.hooli.user.resolvedb.net

Dual Namespace Addressing

Organizations receive both a human-readable vanity name and a stable hash ID:

Both resolve to identical data:

config.settings.hooli.user.resolvedb.net      # vanity (default)
config.settings.a7f3b2c4e8d9f012.user.resolvedb.net  # hash (privacy mode)

Use cases:

• Vanity name: Default for readability, documentation, sharing
• Hash ID: Privacy-sensitive contexts where org name shouldn't leak in DNS traffic; stable identifier that survives org renames

Behavior:

• Vanity names are aliases pointing to the underlying hash ID
• Hash IDs are immutable and assigned at namespace creation
• Org renames update the vanity alias without changing the hash ID
• API responses include both identifiers (see Claiming a Namespace)

Hash ID Security Requirements:

Security Rationale:

6-8 hex characters (24-32 bits) provides collision at only ~4K-16K namespaces (birthday bound). With 64 bits, collision requires ~2^32 namespaces, providing adequate safety margin.

Namespace Claim:

_claim.hooli-user.user.resolvedb.net   TXT  "v=rdb1;pubkey=<ed25519-base64>;sig=<signature-base64>;exp=1735689600"
_claim.hooli.user.resolvedb.net        TXT  "v=rdb1;id=a7f3b2c4e8d9f012;org=hooli;admin=admin@hooli.xyz;verified=true"

Claim Signature Verification

Signature Scope:

The signature in claim records MUST cover a canonicalized representation:

signed_data = SHA256(
    namespace_name_lowercase ||  # "hooli-user" or "hooli"
    ":" ||
    pubkey_bytes ||              # 32-byte Ed25519 public key
    ":" ||
    exp_timestamp                # Big-endian 64-bit Unix timestamp
)

signature = Ed25519.sign(owner_private_key, signed_data)

Verification Process:

def verify_claim(claim_record):
    # 1. Parse claim fields
    namespace = claim_record.name.split('.')[1]  # Extract from _claim.<namespace>...
    pubkey = base64_decode(claim_record['pubkey'])
    sig = base64_decode(claim_record['sig'])
    exp = int(claim_record['exp'])

    # 2. Check expiration
    if exp < current_unix_timestamp():
        return ClaimResult.EXPIRED

    # 3. Reconstruct signed data
    signed_data = sha256(
        namespace.lower().encode() + b':' +
        pubkey + b':' +
        exp.to_bytes(8, 'big')
    )

    # 4. Verify signature
    if not ed25519_verify(pubkey, signed_data, sig):
        return ClaimResult.INVALID_SIGNATURE

    return ClaimResult.VALID

Key Rotation:

To rotate keys, the owner signs with the OLD key authorizing the NEW key:

The signature for rotation covers: new_pubkey || ":" || prev_pubkey || ":" || exp

Revocation:

Compromised keys are revoked by publishing a revocation record signed by any valid key in the chain:

System Namespace (system.resolvedb.<tld>)

Reserved for health, metrics, and status.

Namespace Registration

Naming Rules

Reserved Namespaces

The following namespaces cannot be claimed by users:

Pattern Matching:

Namespaces matching these patterns are also reserved:

• ns[0-9]* - Any nameserver-like pattern
• v[0-9]+ - Version-like patterns (conflicts with protocol version)
• test*, dev*, staging* - Reserved for platform testing

Validation Implementation:

fn is_reserved_namespace(name: &str) -> bool {
    let lower = name.to_lowercase();

    // Exact matches
    const RESERVED: &[&str] = &[
        "public", "system", "registry", "admin", "root",
        "api", "www", "cdn", "dns", "mail", "email", "smtp", "imap", "mx",
        "http", "https", "ftp", "ssh", "sftp", "resolvedb", "rdb",
        "hooli", "demo", "example", "test"
    ];
    if RESERVED.contains(&lower.as_str()) { return true; }

    // Pattern matches
    if lower.starts_with('_') { return true; }       // DNS convention
    if lower.len() <= 2 { return true; }             // Too short
    if lower.starts_with("ns") && lower[2..].chars().all(|c| c.is_ascii_digit()) { return true; }
    if lower.starts_with('v') && lower[1..].chars().all(|c| c.is_ascii_digit()) { return true; }

    false
}

Claiming a Namespace

Namespaces are claimed via the API:

curl -X POST https://api.resolvedb.io/v1/namespaces \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "hooli", "public_key": "<ed25519-pubkey>"}'

Response includes both identifiers:

{
  "name": "hooli",
  "id": "a7f3b2c4e8d9f012",
  "owner": "user-12345",
  "created": 1704067200
}

The claim record is then queryable via either identifier:

_claim.hooli.user.resolvedb.net   TXT  "v=rdb1;id=a7f3b2c4e8d9f012;pubkey=<ed25519>;owner=<user-id>;created=1704067200"
_claim.a7f3b2c4e8d9f012.user.resolvedb.net  TXT  "v=rdb1;id=a7f3b2c4e8d9f012;name=hooli;pubkey=<ed25519>;owner=<user-id>;created=1704067200"

Renaming a namespace:

curl -X PATCH https://api.resolvedb.io/v1/namespaces/hooli \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "hooli-v2"}'

The hash ID (a7f3b2c4e8d9f012) remains stable; existing queries using the hash continue to work. Queries using the old vanity name return notfound after rename.

Access Control Model

Cross-Namespace Access:

• public.* namespaces: readable by all, writable by registered providers
• user.* namespaces: private by default, owner controls access
• Access grants are stored in _acl.<namespace>.user.resolvedb.<tld>

Query Format

Structure

Formal Grammar (ABNF)

; Query structure
query         = operation "." [params "."] resource "." namespace "." version ".resolvedb." tld
operation     = "get" / "put" / "delete" / "list" / "search" / "info" / "health" / "geoip" / "watch"
params        = encoded-param *("." encoded-param)

; Parameter encodings (all use hyphen separators, NOT colons)
encoded-param = plain-param / b64-param / b32-param / hex-param / auth-param
              / chunk-param / hash-param / geo-param / cursor-param
              / ts-param / nonce-param / limit-param / offset-param

; Plain parameters: alphanumeric, cannot start/end with hyphen (RFC 1035)
plain-param   = ALPHANUM *61(ALPHA / DIGIT / "-") [ALPHANUM]
ALPHANUM      = ALPHA / DIGIT

; Encoding prefixes
b64-param     = "b64-" 1*base64url
b32-param     = "b32-" 1*base32                    ; Case-insensitive encoding
hex-param     = "hex-" 1*HEXDIG
auth-param    = "auth-" (jwt-token / hash-ref)     ; Full JWT or hash reference
hash-ref      = "h-" 32*64HEXDIG                   ; HMAC-SHA256 reference (128+ bits)
chunk-param   = "chunk-" index "-" total "-" hash
hash-param    = "h-" 32*64HEXDIG                   ; Content hash (128+ bits minimum)

; GeoIP: lat/lon with 'd' as decimal separator (colons invalid in DNS)
geo-param     = "geo-" coordinate "-" coordinate
coordinate    = ["-"] 1*3DIGIT ["d" 1*6DIGIT]      ; e.g., 40d7128 for 40.7128

; Self-parsed public-service params (the parser keeps these labels intact and
; the service decodes them; see the Units / Sun / Moon service sections).
; 'd' = decimal point, leading 'n' = negative sign, '_' separates lat/lon.
units-param   = number "-" unit "-to-" unit        ; e.g., 100-c-to-f, n40-c-to-f
number        = ["n"] (1*DIGIT ["d" 1*DIGIT] / "d" 1*DIGIT)  ; n=neg, d=decimal
unit          = 1*8(ALPHA / DIGIT)                  ; closed-table slug (c, km, mph, …)
sun-loc       = label / latlon / ip-param / w3w-param  ; weather location grammar
latlon        = signed-coord "_" signed-coord       ; e.g., 51d4769_-0d0005
signed-coord  = ["-"] 1*3DIGIT ["d" 1*DIGIT]
moon-date     = 4DIGIT "-" 2DIGIT "-" 2DIGIT        ; strict YYYY-MM-DD (UTC)

; Pagination
cursor-param  = "cursor-" (1*43base64url / hash-ref)  ; Max 63 chars per label
limit-param   = "limit-" 1*4DIGIT                  ; 1-1000
offset-param  = "offset-" 1*10DIGIT

; Replay protection (required for auth queries)
ts-param      = "ts-" 10DIGIT                      ; Unix timestamp
nonce-param   = "nonce-" 8*16ALPHANUM              ; Random, unique per request

; Structural elements
resource      = label
namespace     = label *("." label)
version       = "v" 1*DIGIT
tld           = "com" / "net" / "org" / "io"

; Labels per RFC 1035: alphanumeric start/end, max 63 chars
label         = ALPHANUM *61(ALPHA / DIGIT / "-") [ALPHANUM]

; Character classes
base64url     = ALPHA / DIGIT / "-" / "_"          ; URL-safe, no padding
base32        = %x41-5A / "2" / "3" / "4" / "5" / "6" / "7"  ; A-Z, 2-7
jwt-token     = 3*(base64url ".") base64url        ; header.payload.signature format
index         = 1*DIGIT
total         = 1*DIGIT
hash          = 16*64HEXDIG                        ; Minimum 64 bits for collision resistance

Grammar Notes:

• All prefixes use hyphens (-), never colons (:) - colons are invalid in DNS labels per RFC 1035
• Labels MUST start and end with alphanumeric characters (RFC 1035 Section 2.3.1)
• JWT tokens in auth- SHOULD use hash references (auth-h-<hash>) for tokens exceeding 63 chars
• Hash references (h-) require minimum 32 hex chars (128 bits) for brute-force resistance

Operations

Parameter Encoding

Parameters requiring special characters are encoded using DNS-safe prefixes. All prefixes use hyphens (-) as separators since colons are not valid in DNS labels per RFC 1035.

Security Token Prefixes

For use cases requiring enhanced security guarantees beyond basic authentication, UQRP defines three specialized token prefixes. These patterns provide cryptographic guarantees that prevent enumeration, privacy leakage, and cross-tenant access.

Blind Device Token (bdt-)

Provides device identity without exposing device IDs in queries. Used for IoT and industrial configurations.

Token Derivation:

device_secret = HKDF-SHA256(
    ikm  = factory_master_secret,
    salt = device_id,
    info = "resolvedb-bdt-v1"
)
blind_token = hex(SHA256(device_secret || factory_id || epoch_week)[0:16])

Query Format:

Example (the 00000000 prefix marks the seeded demo token; production tokens are full 128-bit hashes):

Validation:

1. Server maintains index of blind_token → device_id mappings
2. Accepts tokens for current week AND previous week (seamless rotation)
3. Returns E018 (bdtinvalid) for unknown tokens

Response Encryption: Responses MAY be encrypted with the device's derived secret:

Security Properties:

Cohort Token Pattern (ctp-)

Enables server-side user targeting without exposing user identity or targeting rules in queries.

Token Structure:

cohort_token = base64url(AES-256-GCM(
    key   = app_secret,
    nonce = random(12),
    data  = CBOR({
        "u": SHA256(user_id)[0:8],      // 8-byte user hash
        "s": segment_bitmap,             // 4-byte bitmap (32 targeting bits)
        "t": floor(unix_time / 300)      // 5-minute bucket
    })
))

Segment Bitmap (32 bits):

Bit 0:  is_premium         Bit 16: experiment_a
Bit 1:  is_beta_user       Bit 17: experiment_b
Bit 2:  is_internal        Bit 18: experiment_c
Bit 3:  (reserved)         Bit 19: experiment_d
Bit 4:  platform_ios       Bit 20-23: (reserved)
Bit 5:  platform_android   Bit 24: locale_en
Bit 6:  platform_web       Bit 25: locale_es
Bit 7:  platform_desktop   Bit 26: locale_fr
Bit 8:  region_na          Bit 27: locale_de
Bit 9:  region_eu          Bit 28: locale_ja
Bit 10: region_apac        Bit 29: locale_zh
Bit 11: region_latam       Bit 30: locale_pt
Bit 12-15: tier (0-15)     Bit 31: custom_flag

Query Format:

Example:

Validation:

1. Server decrypts token with app's registered secret
2. Validates timestamp (reject if >5 minutes old)
3. Evaluates targeting rules against segment bitmap
4. Returns evaluated flag values, NOT targeting rules

Security Properties:

Error Codes:

Namespace-Bound Signature (sig-)

Cryptographically binds queries to a specific tenant namespace, preventing cross-tenant access even with stolen tokens.

Signature Derivation:

timestamp = unix_epoch_seconds()
material = UTF8(operation + "." + resource + "." + namespace + ".v1|" + timestamp + "|" + tenant_id)
signature = hex(HMAC-SHA256(tenant_query_key, material)[0:8])

Query Format:

Example (the 00000000 prefix marks the seeded demo signature):

Validation:

1. Extract namespace from query FQDN
2. Look up tenant's tenant_query_key by namespace
3. Recompute expected signature using extracted timestamp
4. Constant-time compare signatures
5. Verify timestamp within 5-minute window
6. Return E018 (siginvalid) for any failure

Combined with JWT (Defense in Depth): For maximum security, combine signature validation with JWT:

Server verifies:

1. JWT claims contain matching tenant field
2. Query namespace matches JWT tenant
3. Signature is valid for query namespace

Security Properties:

Error Codes:

Namespace Query Token (auth-rdbq…)

Status: Implemented (record sync v1). An opaque bearer token that gates reads of private namespaces on resolvedb-core DNS nodes. Tokens are minted by the management API and replicated to every DNS node (as SHA-256 digests) over the internal record-sync feed — no shared signing keys are provisioned across nodes, and a ~300-byte JWT would not fit in a 63-byte DNS label.

Token Format:

• Charset is lowercase base32hex, so the token survives case-insensitive DNS handling unchanged.
• As a params label, auth- + 56 = 61 chars — within the 63-byte label limit (RFC 1035).

Issuance (management API, namespace owner only):

# Mint (plaintext returned exactly once; only the SHA-256 digest is stored)
curl -X POST https://api.resolvedb.com/api/v1/namespaces/:id/query_tokens \
  -H "Authorization: Bearer <jwt>" \
  -d '{"name":"prod-reader","expires_in_days":30}'   # max 365

# List (no plaintext) / revoke (propagates to DNS nodes in seconds)
curl https://api.resolvedb.com/api/v1/namespaces/:id/query_tokens
curl -X DELETE https://api.resolvedb.com/api/v1/namespaces/:id/query_tokens/:token_id

Query Format:

Enforcement (nodes with record sync enabled):

1. public namespace: no token required.
2. Public-read namespaces: a namespace the operator has flagged public_read=true (synced via sync.v1, see below) is answered tokenless and UNMETERED, exactly like public. This is how the hooli demo namespaces are served once migrated off DEMO_SEED to API-managed records. The flag is operator-only (never customer-settable) and requires sync: a sync-disabled node cannot consult it (see the parity note). A fleet-wide kill-switch PUBLIC_READ_DISABLED=true neutralizes the public-read branch without a Rails round-trip.
3. Demo namespaces (hooli, hooli-staging, hooli-dev, demo): answered only when the node runs with DEMO_SEED=true; REFUSED otherwise. This is the reversible safety net retained alongside (2) during the migration.
4. Any other namespace: the query MUST carry an auth- token whose SHA-256 digest is synced, unexpired, and bound to that exact namespace. Any failure (missing/unknown/expired/revoked token, wrong namespace, unknown namespace) returns rcode REFUSED — deny by default, on both plain DNS and DoH.
5. Namespace labels are ASCII-lowercased before matching; mixed-case queries behave identically to lowercase ones.
6. Tokens are opaque to the server: whatever auth- value is presented is hashed and looked up; rdbq-shaped tokens are never parsed as JWTs.

public_read wire contract (sync.v1): the namespace payload on BOTH the event feed (namespace.upserted) and the snapshot serializer carries an additive boolean public_read (DB default false):

{ "name": "hooli", "customer_id": 42, "public_read": true }

It is #[serde(default)] on the core deserializers (absent ⇒ false, fail-closed for old/partial-rollout events), so a node populates its public-read set on its FIRST snapshot. A public_read flip to false, or a namespace.deleted, removes the namespace from the set (tokenless reads revoked).

Parity note (sync-disabled nodes): public-read is a sync-only capability. A node running WITHOUT sync (SYNC_URL/SYNC_TOKEN unset) has no synced namespace state and therefore serves ONLY public and — when DEMO_SEED=true — the hard-coded demo namespaces. It NEVER honors public_read; this is intentional and fail-closed.

Caching: authorized private-namespace answers are returned with TTL 0 so resolvers and intermediaries do not cache token-keyed answers. The token is part of the qname, so any cache key would include it regardless; TTL 0 removes the replay window entirely.

Residual risk (documented): qnames containing tokens appear in resolver logs. Mitigations: short-lived tokens (≤365 days, default 30), instant revocation via the sync feed, TTL 0, and DoH/DoT transport.

Storage Lifetime vs DNS Cache TTL (two distinct concepts)

Hosted records carry two independent, easily-confused notions of "time to live". Treat them separately:

Rules:

• A stored record is persistent by default. Storage expiry is opt-in: supply an explicit expires_at (must be in the future) or expires_in seconds-from-now (0 clears expiry, making the record permanent again).
• The DNS cache TTL (ttl_seconds) is a caching concern only and MUST NEVER be used to derive the storage lifetime. Setting a short cache TTL does not and must not delete the underlying record.
• Authenticated private-namespace answers keep DNS cache TTL 0 (see Caching above) regardless of the record's storage lifetime; the two are orthogonal. A persistent record served under a token still answers with TTL 0.

In sync.v1, expires_at is ISO8601-or-null; null means non-expiring. The DNS nodes lazily drop a synced record only when it carries a non-null expires_at whose time has passed — persistent (null) records are never expired.

Security Token Summary

RFC Conformance

All security token prefixes conform to:

• RFC 1035: Labels ≤63 chars, FQDN ≤253 chars, valid chars [a-z0-9-]
• RFC 4648: Base64url encoding for CTP tokens
• RFC 5869: HKDF key derivation for BDT
• RFC 5116: AEAD (AES-256-GCM) for CTP encryption
• RFC 2104: HMAC for NBA signatures

Usage Metering (usage.v1)

Status: Implemented; OFF by default. A counting-only telemetry pipeline that tallies authenticated (PrivateOk) queries per customer for display on the management API. It is display-grade telemetry, not a billing input (see the estimated flag below): it never gates, throttles, or prices a query, and it can never slow or fail DNS resolution. It is the inverse direction of record sync — sync.v1 is API → fleet; usage.v1 is fleet → API.

Hot-path safety (HARD CONSTRAINT). Emission is best-effort and fully off the DNS resolution path. The core node enqueues one event onto a bounded in-memory channel via a non-blocking try_send; a full channel drops the event (and increments resolvedb_usage_events_dropped_total) rather than blocking. A background task drains the channel to Redis. If Redis is unreachable the meter is a no-op. Consequently the pipeline is lossy by design and counts are an estimate, not a guarantee.

What is counted. Only successful PrivateOk queries — a private namespace answered with ≥1 record by a valid auth-rdbq… query token. An authenticated miss/NODATA, lazy-expired, or error is NOT counted (usage = authed hits only). Public, demo, refused, and unauthenticated queries are structurally un-meterable (no customer_id to attribute to) — this also denies an anonymous-flood attacker any way to inflate a customer's count. Note the divergence from query_stats.v1: an authenticated miss STILL records a tenant miss row there (analytics wants it). stats = all authed (any status); usage = authed hits only.

Transport (core → API). Core XADDs each event to a Redis stream (STREAM_KEY = "resolvedb:usage", MAXLEN ~ 100000); Rails consumes it with XREAD from a Postgres-persisted high-watermark. Stream event fields:

type=authed_query                  # constant discriminator
customer_id=<i64>                  # namespace owner at emit time (point-in-time attribution)
token_id=<sha256-hex>              # the query token's SHA-256 DIGEST (non-secret), or empty
namespace=<lowercase-label>
ts=<unix-seconds>
transport=dns|doh

Privacy invariant (enforced by tests). The event carries ONLY the closed-set attribution tuple above. It NEVER carries the raw token, the qname, query params, or the client IP. token_id is the same stable SHA-256 digest the fleet already syncs for token matching — knowing it does not let anyone make an authenticated query (the plaintext token, which lives only in the qname, is required for that).

Aggregation (API side). Counts are additive (one raw event per query). The consumer folds each event +1 into usage_counters, bucketed by period (hour / day / billing-month) per (customer, namespace, token, transport). Idempotency is the monotonic Redis stream-id high-watermark (usage_ingest_cursors), advanced in the same DB transaction as the increments: an at-least-once redelivery is below the watermark and dropped, so it is never double-counted. An event for a customer_id not yet known locally (sync lag) is deferred — the watermark is held so it is retried on a later tick, not silently skipped past. Rows are pruned past USAGE_RETENTION_DAYS.

Read surface. GET /api/v1/usage gains a metered object, scoped (Pundit) to the calling customer's own customer_id:

"metered": {
  "since": "...", "until": "...",
  "estimated": true,                       // reflects the lossy hot path above
  "total_authenticated_queries": 4210,
  "by_namespace": [ { "name": "acme", "count": 4210 } ],
  "tier": "free",
  "tier_allowance": 100000                 // read-only display; no price, no enforcement
}

tier_allowance is the per-tier included allowance from configuration (x.resolvedb.metering_allowance); it is informational only and gates nothing. Stripe billing (now implemented, OFF by default) adds a soft_cap_state block to this metered object for an "approaching / over your included queries" upgrade prompt, but it remains display-only — estimated: true is always present and no code path turns a counter into a charge, an invoice, or a query block. These counts are never a billing input.

Operational note. Both ends are gated off by default and share the resolvedb:usage stream key: core enables on USAGE_REDIS_URL; the Rails consumer enables on USAGE_INGEST_ENABLED + USAGE_REDIS_URL. See docs/runbooks/usage-metering-launch.md.

Query-Stats (query_stats.v1)

Status: Implemented; OFF by default. A per-query analytics pipeline that records one row per UQRP query (every product query, not just authenticated ones) for the dashboard Query Analytics page. Like usage.v1 it is the inverse direction of record sync (fleet → API), display-grade, and can never slow or fail DNS resolution. It is the higher-volume sibling of usage.v1: usage metering counts only authenticated queries for billing display; query-stats counts every query for analytics.

Hot-path safety (HARD CONSTRAINT). Identical discipline to usage.v1: emission is a single non-blocking try_send onto a bounded channel (drop-on-full, resolvedb_query_stat_events_dropped_total), drained to Redis by a background task. No-op when QUERY_STAT_REDIS_URL is unset or RESOLVER_REGION is unset/unknown. A second always-present gauge resolvedb_query_stat_meter_enabled (0 disabled / 1 active) makes a silent disable (e.g. a per-host RESOLVER_REGION cleared by an ops change while Redis stays configured) alertable rather than invisible.

Single emit site. Both DNS callers (search and lookup) route through one handle_uqrp_lookup chokepoint, which emits exactly once — every UQRP query is counted exactly once (no under-count on lookup, no double-count on search). Apex/NS static queries never reach it and are never counted. The DoH transport keeps its own gate path and does not emit query-stats in v1 (out of scope; see the runbook).

Transport (core → API). Core XADDs each event to a Redis stream (STREAM_KEY = "resolvedb:query_stats", MAXLEN ~ 1000000); Rails consumes it with XREAD from a Postgres-persisted high-watermark. Stream event fields:

type=query_stat                    # constant discriminator
resource=<closed class>            # weather|forecast|stock|forex|crypto|geoip|records|schema (NEVER the raw label)
version=<[a-z0-9]{1,16}>           # charset-validated both sides ("v0" substituted on failure)
status=hit|miss|expired|error|refused  # closed outcome enum
region=nyc1|sfo3|ams3              # RESOLVER_REGION, validated against the closed set
ts=<unix-seconds>
customer_id=<i64>                  # PRESENT ONLY for PrivateOk (authenticated) queries
namespace=<[a-z0-9._-]{1,63}>      # PRESENT ONLY for PrivateOk; charset-bounded (else dropped)

Status mapping (closed, total). Set per-arm where the outcome is known: answered with ≥1 record → hit; resolved-but-empty NODATA → miss; lazy-expiry NODATA → expired (emitted EXCLUSIVELY from the expiry arm, never conflated with ordinary NODATA); a gate/auth denial (REFUSED) → refused (its OWN status, an expected outcome, set explicitly at the gate arm); genuine failure (ServFail / internal / unsupported rtype / service error) → error. A UQRP parse error emits nothing (not a product query). refused and error are distinct: refused is an authz denial (deny-by-default, missing/invalid token), error is a true failure.

Deploy ordering (BLOCKING for the refused enum change). Rails skips an unrecognized status AND advances the ingest cursor past it (permanent silent drop). Therefore Rails (model inclusion + QueryStats::Ingestor::VALID_STATUSES) MUST accept refused and be confirmed consuming BEFORE the core fleet begins emitting it. Never deploy core ahead of Rails for this change — see docs/runbooks/query-stats-refused-launch.md.

Privacy invariant (enforced by tests). The event is a closed struct, structurally incapable of carrying the qname, query params, the raw or hashed token, or the client IP. resource is a closed class (unknown → records, never an echo of the untrusted label). customer_id/namespace are sourced ONLY from the on-node MeterAttribution (PrivateOk, token-bound) and travel together — they are absent (NULL-tenant) for public/demo/refused/unauthenticated queries.

Ingest & tenancy (API side). Each event becomes one query_stats row (insert_all!, bounded batch). namespace_id is set ONLY when the event carries both customer_id and namespace, the customer exists locally, AND that exact namespace is owned by that customer_id (Namespace.find_by(name:, customer_id:)) — the proven cross-tenant guard. A forged numeric customer_id, an unowned namespace, or absent fields → namespace_id = NULL. No defer path (unlike usage.v1): an unknown/unverifiable customer_id is inserted IMMEDIATELY as NULL-tenant, so one unknown-but-recent id can never head-of-line- block the high-volume watermark. Idempotency is the monotonic Redis stream-id high-watermark (query_stat_ingest_cursors), advanced in the same DB transaction as the inserts (at-least-once redelivery never double-inserts). Rows prune past QUERY_STATS_RETENTION_DAYS (default 30; hourly prune at fleet QPS). latency_ms is NULL in v1 (no hot-path timing).

Read surface. GET /api/v1/query_logs (Pundit-scoped to the caller's namespaces). The meta.total is a recent-window (24h) count — never an all-time scan over a table that grows to hundreds of millions of rows — surfaced with meta.total_window_hours.

Operational note. Both ends are gated off by default and share the resolvedb:query_stats stream key: core enables on QUERY_STAT_REDIS_URL (+ a known RESOLVER_REGION); the Rails consumer enables on QUERY_STATS_INGEST_ENABLED + QUERY_STATS_REDIS_URL. See docs/runbooks/query-stats-launch.md.

Dataset Registry (BIN/GTIN, datasets resource, v1)

Gated OFF by default (DATASETS_ENABLED). When off, the reserved datasets resource is REFUSED and dataset sync events are dropped.

ResolveDB serves publisher-attested reference-data facts (BIN issuer lookups, GTIN identity) on the public free-tier read surface. ResolveDB is NOT a proprietary dataset vendor: every dataset carries a mandatory, surfaced license and provenance, and the differentiator is that facts are DNSSEC-signed and operator-attested and cacheable. Publishing and attestation are the gated/paid surface (in the Rails API); reads are public.

Legal guardrail. ResolveDB never ingests, scrapes, or redistributes Visa VBASS or GS1 GEPIR data. license + provenance are non-null on every dataset and shipped seed data is labeled SYNTHETIC.

Two signature layers (never conflated)

1. DNSSEC RRSIG — transport integrity only (the zone signer signs every answer, including dataset TXTs). It cannot carry attestation: a draft TXT would still be RRSIG-valid.
2. Attestation signature — a payload-level Ed25519 signature over the canonical manifest tuple (below), in a SEPARATE trust domain from DNSSEC. It is produced ONLY in the Rails API (single chokepoint) and replicated to the DNS fleet as opaque bytes; the core never holds the attestation private key and (in MVP) does not self-verify — it stores and serves the bytes. Clients verify BOTH layers.

Canonical manifest (the signed envelope)

Byte-deterministic so the signer and any verifier agree:

canonical = "rdb-attest.v1\n"
          + "name="       + name        + "\n"
          + "version="    + version     + "\n"   // semver
          + "license="    + license     + "\n"   // SPDX id or free text, non-empty
          + "provenance=" + provenance  + "\n"   // non-empty
          + "sha256="     + sha256_hex_lowercase  // 64 lc hex of the bulk content

Field order is FIXED; values are NFC UTF-8 with \n and \ forbidden per field. sha256 binds the manifest to off-DNS bulk content (a CDN URL); clients fetch and re-hash out of band. The content URL is untrusted at fetch time — only the sha256 is authoritative. Signature = Ed25519(attestation_sk, canonical_bytes).

Query formats (single params label)

Both formats encode a compound key inside ONE DNS label, using hyphen sub-encoding (colons are illegal in DNS labels per RFC 1035). The -v- / -k- 3-byte infix markers cannot be produced by a valid slug (^[a-z0-9-]{1,40}$, no leading/trailing hyphen).

# Manifest — latest version (alias)
dig TXT manifest.bin-acme.datasets.public.v1.resolvedb.net +short

# Manifest — pinned version (d -> . decode: 1d2d0 = 1.2.0)
dig TXT manifest.bin-acme-v-1d2d0.datasets.public.v1.resolvedb.net +short

# Identity — BIN (6-8 digits)
dig TXT identity.bin-acme-k-411111.datasets.public.v1.resolvedb.net +short

# Identity — GTIN (8/12/13/14 digits)
dig TXT identity.gtin-acme-k-00012345600012.datasets.public.v1.resolvedb.net +short

• Slug = left of the -v-/-k- marker, validated ^[a-z0-9-]{1,40}$.
• Version decode: d → ., then strict ^\d+\.\d+\.\d+$ semver (a manifest-local step, NOT weather coordinate decoding).
• Item key charset/length is bounded by the slug-inferred kind (bin-* ⇒ 6–8 digits, gtin-* ⇒ 8/12/13/14 digits). The authoritative kind is the stored row's existence.

Response schemas (TXT)

Manifest (;-joined key=value, ASCII, 255-byte TXT chunking as needed):

v=rdb-attest.v1;ds=bin-acme;ver=1.2.0;lic=CC-BY-4.0;prov=SYNTHETIC-sample;
sha256=<64hex>;url=https://cdn.resolvedb.../bin-acme-1.2.0.jsonl;
att=attested;attsig=<base64 ed25519 sig>;attkid=ak1;atts=<unix-ts>

Only att=attested is ever served (unattested versions are never stored). Field bounds: ds ≤ 40, ver ≤ 16, lic ≤ 128, prov ≤ 256, url ≤ 2048, sha256 = 64 hex, attsig = base64 Ed25519, attkid ≤ 16. The rendered value must be ≤ 3500 bytes (the same MAX_RENDERED_VALUE_BYTES ceiling the sync writer enforces; oversized values are dropped, never stored).

Identity:

Per-item integrity = the manifest sha256 over the bulk content + DNSSEC + the row's existence implying its dataset is attested. Per-item attestation signatures are deferred to v2.

Client verification steps

1. Validate the DNSSEC chain on the TXT answer (transport integrity).
2. Rebuild the canonical manifest tuple from the served fields and verify attsig with the attestation public key for attkid. Public keys are distributed via the DNSSEC-signed well-known manifest.keys.datasets.public.v1.resolvedb.net TXT and the docs.
3. Fetch the url bulk content out of band and confirm its SHA-256 equals sha256 (the URL is untrusted; only sha256 is authoritative).

Status / error mapping

Reserved storage prefixes

manifest. and identity. (with resource datasets, namespace public, version v1) are RESERVED storage-key prefixes. Customers cannot create a public-namespace record whose rendered key would begin with them. Dataset slugs are globally unique, so manifest.<slug>.…/identity.<slug>.… keys are partitioned per publisher by construction — a dataset write can never poison a public-service key or another publisher's data.

Temporal validity & as-of queries (identity facts only)

Gated OFF by default behind TEMPORAL_FACTS_ENABLED, nested under DATASETS_ENABLED (both ends must be on). When off, -t- is REFUSED at parse (FormErr) and identity replicates as a single current fact exactly as before. Manifests are immutable by sha256 and have NO temporal form. Records-side temporal is deferred (no attestation anchor for the long-TTL rule).

Each identity item (a single BIN/GTIN) may carry one or more validity windows, each a half-open interval [valid_from, valid_to). An as-of query selects the single window containing the as-of instant:

# Current identity (the window containing "now")
dig TXT identity.bin-acme-k-411111.datasets.public.v1.resolvedb.net +short

# As-of by unix seconds
dig TXT identity.bin-acme-k-411111-t-1500000000.datasets.public.v1.resolvedb.net +short

# As-of by calendar date (YYYY-MM-DD, interpreted at 00:00:00Z)
dig TXT identity.bin-acme-k-411111-t-2023-11-14.datasets.public.v1.resolvedb.net +short

• The as-of token rides on the LAST -t- infix of the identity params label (unambiguous: item keys are pure digits and slugs cannot end in -). It is ONLY accepted for identity; manifests reject it.
• asof is EITHER unix seconds (1–10 digits, 0 ≤ v ≤ 253402300799) OR an exact YYYY-MM-DD calendar date at midnight UTC. Anything else ⇒ FormErr with a single, non-differentiated negative answer (no oracle).
• Selection is half-open: valid_from <= asof < valid_to. Absent valid_from = −∞, absent valid_to = current/open. No -t- ⇒ asof = now (server clock). The server never serves a window with valid_from > asof (no future disclosure) and never widens beyond attested data.
• Windows for one item never overlap (enforced in the Rails API by a per-item advisory lock + a Postgres EXCLUDE constraint). A residual ambiguity fails closed (NODATA).

TTL rule (settled-past ⇒ immutable). A selected window whose valid_to is finite AND strictly in the settled past (valid_to < now − 3600s skew margin) is provably immutable and served with the long TTL_IMMUTABLE (7 days). A current/open window, or one that ended within the skew margin, is served with the short TTL_STANDARD (1 hour). The server clock is the only time source; a client-supplied as-of never widens the TTL.

Storage shape (sync writer ↔ serving dispatch, both in core).

# Per-item temporal index (TXT VALUE; ';'/',' allowed like the manifest envelope)
identity.<slug>.<item-key>.tindex.datasets.public.v1
  v=rdb-tindex.v1;ds=<slug>;k=<item>;w=<vf>,<vt>;w=…
  (vf ∈ {ninf, unix-digits}; vt ∈ {cur, unix-digits}; ≤ 64 windows)

# Per-window fact record (the existing rdb-id.v1 envelope, verbatim)
identity.<slug>.<item-key>.t.<vf-token>.datasets.public.v1
  (vf-token = "ninf" | unix-digits)

Serving is deterministic, two retrievals, no range scan: retrieve the tindex, select the unique window for the as-of instant, then retrieve that window's fact key. A tindex miss falls back to the legacy single key (a pre-temporal item).

Stock Service — Exchange Reference Provenance (stock)

The stock resource returns a real-time US quote for a ticker. The live price object is venue-anonymous (the upstream snapshot does not state which venue a trade executed on). Separately, ResolveDB can surface the ticker's listed primary exchange as ISO-10383 MIC, drawn from a STATIC, DATED reference snapshot embedded in the server.

These two facts are NEVER conflated. The exchange fields are honest reference-data provenance with an as-of and a source — they answer "what is the listed primary exchange for this ticker per a dated reference snapshot," not "this price executed on this venue."

Query forms

# Bare ticker (price; provenance attached when fresh + known)
get.AAPL.stock.public.v1.resolvedb.net

# Pin an explicit exchange MIC with the `-x-<MIC>` infix on the ticker label
get.AAPL-x-XNAS.stock.public.v1.resolvedb.net

The MIC is a fixed 4-letter ISO-10383 code from a closed allowlist: XNAS, XNYS, XASE, ARCX, BATS, IEXG. -x- is recognized only by the finance validator (the UQRP parser keeps the single stock params label intact; no generic decode). Non-US venues are not supported in v1.

Response fields (TXT, v=rdb1;s=ok;t=data)

Base fields: sym, prc, chg, pct, vol, opn, hi, lo (plus optional extended h52/l52/pe/div).

Exchange provenance is an all-three-or-none triple, emitted right after sym and before prc:

Provenance is surfaced ONLY when the snapshot is fresh (within MAX_REFERENCE_AGE_DAYS, default 120) AND the ticker is known to the reference map. When the snapshot is stale, the ticker is unknown, or the dataset is empty, the price still serves but bare (no exch* fields) — degrade, never assert a venue from stale/missing data.

Error contract

A bare ticker never fails on the exchange dimension. An explicit -x-<MIC> query that cannot be served — unsupported/malformed MIC, ticker unknown to the reference map, listed exchange ≠ requested MIC, or a stale reference snapshot — returns one uniform fail-closed outcome: ExchangeUnavailable → FormErr (E005). The four cases collapse to a single DNS code on purpose, so a client cannot use a NODATA-vs-FormErr difference to enumerate which tickers exist in the reference map. Over UDP/TCP DNS this is (intentionally) indistinguishable from any other invalid-input FormErr; the sanitized d=Exchange unavailable detail reaches only /query HTTP and DoH-with-body, and never echoes the requested MIC.

Dataset provenance & licensing

The embedded data/ticker_mic.csv ships SYNTHETIC (hand-authored placeholders) by default. Embedding REAL Polygon/Massive-derived ticker→MIC reference data is a blocking operator ToS sign-off (mirrors the dataset- registry VBASS/GEPIR guardrail): confirm in writing that the provider terms permit embedding + redistributing the derived dataset in the (private) binary before swapping in real data. With the dataset absent/empty the feature degrades to price-only and explicit -x- queries fail closed. See docs/runbooks/stock-exchange-launch.md.

Query Examples

# Simple (no params)
get.weather.public.v1.resolvedb.net

# With location param (plain alphanumeric)
get.newyork.weather.public.v1.resolvedb.net

# Base64 encoded params (JSON with special chars)
# {"lat":40.7128} -> eyJsYXQiOjQwLjcxMjh9
get.b64-eyJsYXQiOjQwLjcxMjh9.location.public.v1.resolvedb.net

# Authenticated (JWT token)
get.auth-eyJhbGciOiJFZDI1NTE5In0.profile.hooli.v1.resolvedb.net

# Chunked data (index-total-hash format)
get.chunk-0-10-abc123.largedata.hooli.v1.resolvedb.net

# Hash-addressed (for long params)
get.h-a1b2c3d4e5f6g7h8.cache.public.v1.resolvedb.net

# Conditional
get.if-modified-since-1704067200.data.user.v1.resolvedb.net

# GeoIP lookup (explicit IP required)
get.ip-8-8-8-8.geoip.v1.resolvedb.net

Units Service (units)

The units resource is a pure-compute, tokenless, unmetered, cacheable public.v1 service that converts a numeric value between two units in the same category. There is no external provider and no network: every conversion factor is a mathematical constant authored in the server, so the answer for a given query never changes (it caches as stable, TTL 86400).

Query format

The whole expression is a single params label that the service parses itself (the UQRP parser keeps it intact; no generic decode). It splits on the literal -to- separator: everything before is <value>-<from>, everything after is <to>. The value is the token before the last - of the left-hand side, so a value token may contain no -.

Value encoding (DNS-safe, colons/dots/signs invalid in labels):

• d is the decimal point (1d5 = 1.5, 0d001 = 0.001, d5 = 0.5).
• A single leading n is a negative sign (n40 = -40).
• Only digits and one d may follow; exponents, embedded signs, and whitespace are rejected. The value is parsed to f64 and any NaN/Inf/overflow is rejected.

Unit slugs are a closed table across five categories. Conversion is only valid within one category; a cross-category pair is an error.

Response fields (TXT, plain)

The response body is a flat key=value string (no v=rdb1 envelope is added by the service; the DNS layer wraps it as t=data;f=text when serving legacy plain bodies). Results are rounded to 6 significant figures and rendered without trailing zeros (so 212, not 212.0000).

# 100 C -> F
dig TXT get.100-c-to-f.units.public.v1.resolvedb.net +short
# "in=100;from=celsius;to=fahrenheit;r=212;cat=temperature"

# -40 C -> F (negative via leading n)
dig TXT get.n40-c-to-f.units.public.v1.resolvedb.net +short
# "in=-40;from=celsius;to=fahrenheit;r=-40;cat=temperature"

# 5 km -> mi
dig TXT get.5-km-to-mi.units.public.v1.resolvedb.net +short
# "in=5;from=kilometre;to=mile;r=3.10686;cat=length"

# 60 mph -> km/h
dig TXT get.60-mph-to-kmh.units.public.v1.resolvedb.net +short
# "in=60;from=mile-per-hour;to=kilometre-per-hour;r=96.5606;cat=speed"

Error contract

All malformed/cross-category inputs collapse to a single FormErr DNS code (no panic, no enumeration oracle). A non-get operation, a non-public namespace, or a non-v1 version is rejected by the generic dispatch before the service runs. Only TXT is answered; other record types return NODATA.

Sun Service (sun)

The sun resource is a pure-compute, tokenless, unmetered, cacheable public.v1 service returning sunrise / sunset / solar-noon / civil-dawn / civil-dusk and day length for a location on the current UTC day. The math is the public-domain NOAA / Meeus low-precision solar-position model; no external provider is consulted (location resolution may geocode a city name — see below).

Query format

<location> reuses the weather service location grammar exactly:

• City name: get.london.sun.public.v1.resolvedb.net
• Coordinates <lat>_<lon> with d as the decimal point and _ separating latitude/longitude (leading - allowed for negatives): get.51d4769_-0d0005.sun.public.v1.resolvedb.net
• By IP: get.ip-8-8-8-8.sun.public.v1.resolvedb.net
• By what3words (hyphens replace dots): get.w3w-filled-count-soap.sun.public.v1.resolvedb.net

Response fields (TXT, plain)

Times are ISO-8601 UTC instants (YYYY-MM-DDTHH:MM:SSZ); day length is XhYm.

Polar edge cases: at high latitudes a day may have no sunrise/sunset. In that case the response carries polar=day (midnight sun) or polar=night (polar night) instead of rise/set, with daylen=24h0m or daylen=0h0m respectively. Solar noon is always defined; dawn/dusk are omitted when twilight does not occur.

# London (summer solstice example output)
dig TXT get.london.sun.public.v1.resolvedb.net +short
# "rise=2024-06-21T03:43:00Z;set=2024-06-21T20:21:00Z;noon=...;dawn=...;dusk=...;daylen=16h38m"

# By coordinates (lat_lon, d=decimal point)
dig TXT get.51d4769_-0d0005.sun.public.v1.resolvedb.net +short

# Polar night (high northern latitude in winter)
# "polar=night;noon=...;daylen=0h0m"

Error contract

Only TXT is answered. Non-get/non-public/non-v1 are rejected by the generic dispatch before the service runs. The result caches for 1 hour (TTL_OP_SUN) so it rolls over to the next day's events without serving stale times.

Moon Service (moon)

The moon resource is a pure-compute, tokenless, unmetered, cacheable public.v1 service returning the lunar phase, illuminated fraction, age, and the next full/new-moon dates. It is location-independent. The math is a low-precision Meeus-style approximation from the mean synodic month and a J2000 reference new moon (accurate to well under a day for phase naming).

Query format

get.moon.public.v1.resolvedb.net               # today (current UTC date)
get.<YYYY-MM-DD>.moon.public.v1.resolvedb.net  # a specific UTC date

The optional date is a single params label with literal hyphens. It is validated strictly as a real calendar date (exactly 10 chars, YYYY-MM-DD, leap-year and month-length aware); an impossible or malformed date is rejected. With no params label the service computes for the current UTC date.

Response fields (TXT, plain)

Phase names: New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent.

# Today
dig TXT get.moon.public.v1.resolvedb.net +short
# "phase=Waxing Gibbous;illum=0.812;age=11.3;next_full=...;next_new=..."

# A specific date
dig TXT get.2024-03-20.moon.public.v1.resolvedb.net +short
# "phase=Waxing Gibbous;illum=0.787;age=10.3;next_full=2024-03-25;next_new=2024-04-08"

Error contract

No params (today) and a valid date both succeed; computation never fails. Only TXT is answered. Non-get/non-public/non-v1 are rejected by the generic dispatch. The result caches for 1 hour (TTL_OP_MOON).

Reserved resource — btc (NOT yet public). A btc chain-stats resource (get.<metric>.btc.public.v1.resolvedb.net, metrics height/fees/ mempool/halving/difficulty) exists in the reference implementation but ships gated OFF behind BTC_SERVICE_ENABLED (default false). While off, the resource behaves as unknown (NODATA) and leaks nothing. Even when enabled it currently serves mock data — every response is tagged src=mock — pending a self-hosted Esplora/bitcoind upstream. It is therefore documented here only as reserved; its query grammar and fields are not yet a stable public contract and may change before launch.

Schema Access (info Operation)

The info operation provides resource metadata and schema definitions in JSON Schema format. Schemas enable:

• LLM-friendly introspection: Rich descriptions, examples, and actionable field documentation
• Client validation: JSON Schema for validating responses
• API discovery: List available resources per namespace

DNS Query Format

Examples:

# Get weather service schema
dig TXT info.weather.public.v1.resolvedb.net +short

# Get GeoIP service schema
dig TXT info.geoip.public.v1.resolvedb.net +short

# List all resources in public namespace (namespace listing)
dig TXT list.schema.public.v1.resolvedb.net +short

HTTP Endpoint

The q parameter accepts any UQRP query format. The parser extracts resource.namespace.version, ignoring operation and parameters. This allows copy-pasting real queries to discover their schema:

# Get schema for a resource
curl 'https://api.resolvedb.io/schema?q=weather.public.v1.resolvedb.net'

# Same result - operation and params ignored
curl 'https://api.resolvedb.io/schema?q=get.seattle.weather.public.v1.resolvedb.net'

# Namespace listing (no resource specified)
curl 'https://api.resolvedb.io/schema?q=public.v1.resolvedb.net'

Response Format (JSON Schema)

{
  "status": "ok",
  "version": "rdb1",
  "namespace": "public",
  "resource": "weather",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://resolvedb.net/schema/public/weather/v1",
    "title": "Weather Schema",
    "description": "Weather data for a location",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "tc": {
        "type": "number",
        "description": "Temperature in Celsius. Use for metric regions.",
        "example": 22.5
      },
      "tf": {
        "type": "number",
        "description": "Temperature in Fahrenheit. Use for US/Imperial regions.",
        "example": 72.5
      },
      "cnd": {
        "type": "string",
        "description": "Current weather condition. Use for display or weather icons.",
        "enum": ["clear", "cloudy", "rain", "snow", "fog"]
      }
    },
    "required": ["tc", "tf", "cnd"]
  },
  "meta": {
    "auth_required": false,
    "rate_limit_tier": "standard",
    "default_ttl": 300
  },
  "dns_format": {
    "query_template": "get.<city>.weather.public.v1.resolvedb.net",
    "placeholders": {
      "city": {"type": "string", "examples": ["seattle", "london", "tokyo"]}
    },
    "example_response": "v=rdb1;s=ok;t=data;f=json;tc=22.5;tf=72.5;cnd=clear"
  },
  "http_format": {
    "endpoint": "GET /resolve?name=get.seattle.weather.public.v1.resolvedb.net&type=TXT",
    "curl_example": "curl 'https://api.resolvedb.io/resolve?name=get.seattle.weather.public.v1.resolvedb.net&type=TXT'",
    "schema_endpoint": "GET /schema?q=weather.public.v1.resolvedb.net"
  },
  "error_responses": [
    {"status": "notfound", "code": "E004", "description": "City not found"},
    {"status": "ratelimit", "code": "E010", "description": "Rate limit exceeded", "retry_after": true}
  ]
}

DNS Response (t=data)

For DNS responses, schemas use t=data response type with f=json:

Large schemas are chunked with SHA-256 hash for integrity:

v=rdb1;s=ok;t=data;f=json;c=1/3;h=<64-char-sha256>;ttl=3600;d=<chunk1>
v=rdb1;s=ok;t=data;f=json;c=2/3;h=<64-char-sha256>;ttl=3600;d=<chunk2>
v=rdb1;s=ok;t=data;f=json;c=3/3;h=<64-char-sha256>;ttl=3600;d=<chunk3>

Access Control

Error responses for private namespaces:

{"status": "error", "message": "Authentication required for non-public namespaces"}

TTL

Schema responses use TTL_OP_INFO = 3600 seconds (1 hour) as schemas change infrequently.

Response Format

TXT Record Response (v1)

Status Codes

Error Codes

Machine-readable error codes for programmatic handling:

Error Response Example:

Error Privacy Mode

For privacy-sensitive namespaces, error responses may leak information about resource existence:

Privacy Mode Behavior:

When privacy mode is enabled for a namespace, servers SHOULD return unified error responses:

# Standard mode (informative):
v=rdb1;s=notfound;err=E004;d=Resource not found
v=rdb1;s=notfound;err=E005;d=Namespace not found
v=rdb1;s=forbidden;err=E009;d=Access denied

# Privacy mode (uniform):
v=rdb1;s=notfound;err=E004;d=Not found or access denied

Configuration:

Privacy mode is set per-namespace via claim record:

Trade-offs:

• Normal: Better debugging, faster issue resolution
• High: Prevents enumeration, hides internal structure

Response Examples

# Success with JSON
v=rdb1;s=ok;t=data;e=plain;f=json;h=a1b2c3d4e5f6g7h8;ttl=300;d={"temp":72,"unit":"F"}

# URL redirect (large data)
v=rdb1;s=redirect;t=url;ttl=3600;d=https://cdn.resolvedb.cloud/blob/abc123

# Multi-record (chunked)
v=rdb1;s=ok;t=multi;c=1/3;seq=1;h=abc123;d=<chunk1>
v=rdb1;s=ok;t=multi;c=2/3;seq=2;h=abc123;d=<chunk2>
v=rdb1;s=ok;t=multi;c=3/3;seq=3;h=abc123;d=<chunk3>

# Streaming endpoint (see WebSocket Session Security below)
v=rdb1;s=ok;t=stream;d=wss://stream.resolvedb.net/session/<session-token>

# Rate limited with retry hint
v=rdb1;s=ratelimit;err=E010;retry=60;ttl=1;d=Rate limit exceeded. Retry after 60s

# Encrypted
v=rdb1;s=ok;t=encrypted;e=aes256gcm;k=<ephemeral-pubkey>;d=<ciphertext>

# GeoIP response
v=rdb1;s=ok;t=data;f=json;ttl=300;d={"country":"US","region":"NY","city":"New York","lat":40.7128,"lon":-74.006}

DNS over HTTPS (DoH)

ResolveDB supports DNS over HTTPS per RFC 8484, providing encrypted DNS queries via HTTP/S.

Endpoints

Content Negotiation & Precedence (/dns-query GET)

/dns-query GET is param-authoritative and deterministic (Cloudflare-compatible):

1. dns= present → WIRE (RFC 8484, unchanged bytes/headers). If BOTH dns= and name= are present, WIRE wins — never an error.
2. else name= present → JSON resolve (the SAME path as /resolve).
3. neither → a fully-static FORMERR 400 (Status:1, Comment a constant string; no echo of any key/value/Accept/qname).

The Accept header is acceptability-only and NEVER routes: a missing or */* Accept (the browser default) with name= resolves to JSON 200 — this is the canonical way to use the JSON API on /dns-query. Because routing is param-driven, there is intentionally no Vary: Accept.

cd and edns_client_subnet are honored on the name= path identically to /resolve (forwarded into the shared resolve, no drift). Validation failures (oversize/invalid name, bad type) return a generic FORMERR that does NOT echo the supplied name/type. Content-Type is always branch-derived: wire → application/dns-message, JSON → application/dns-json; nosniff on every branch including the static 400; JSON answers are always Cache-Control: no-store (authed answers are TTL-0). Both branches flow through the deny-by-default namespace gate — there is no JSON fast-path that skips authorization.

Wire Format (/dns-query)

Standard RFC 8484 DNS wire format over HTTPS.

GET Request:

# Base64url-encode DNS wire format query (no padding)
curl "https://api.resolvedb.io/dns-query?dns=AAABAAABAAAAAAAAB2V4YW1wbGUDY29tAAABAAE" \
  -H "Accept: application/dns-message"

POST Request:

curl -X POST "https://api.resolvedb.io/dns-query" \
  -H "Content-Type: application/dns-message" \
  -H "Accept: application/dns-message" \
  --data-binary @query.bin

Response:

• Content-Type: application/dns-message
• Body: DNS wire format response
• Cache-Control: max-age=<min-TTL> or no-store for errors

JSON API (/resolve)

Google-compatible JSON API for DNS queries. Easier to use from web applications and debugging tools.

Request:

Query Parameters:

Supported Query Types:

Response Format:

{
  "Status": 0,
  "TC": false,
  "RD": true,
  "RA": true,
  "AD": false,
  "CD": false,
  "Question": [
    {"name": "example.com", "type": 1}
  ],
  "Answer": [
    {"name": "example.com", "type": 1, "TTL": 300, "data": "93.184.216.34"}
  ],
  "Authority": [],
  "Additional": [],
  "edns_client_subnet": "1.2.3.0/24",
  "Comment": "Optional comment"
}

Response Fields:

Examples:

# Simple A record lookup
curl "https://api.resolvedb.io/resolve?name=example.com&type=A"

# MX record lookup
curl "https://api.resolvedb.io/resolve?name=gmail.com&type=MX"

# AAAA with DNSSEC
curl "https://api.resolvedb.io/resolve?name=cloudflare.com&type=AAAA&do=true"

# TXT record (SPF, DKIM, etc.)
curl "https://api.resolvedb.io/resolve?name=google.com&type=TXT"

DoH Security

Implementation Status

GeoIP Operation

The geoip operation returns geographic location data for a specified IP address. Following the Privacy by Design principle, the IP address MUST be provided as an explicit parameter.

Query Format

IP Encoding:

• IPv4: Replace dots with hyphens (e.g., 8.8.8.8 → ip-8-8-8-8)
• IPv6: Replace colons with hyphens, :: becomes -- (e.g., 2001:4860:4860::8888 → ip-2001-4860-4860--8888)

Response

{
  "ip": "8.8.8.8",
  "country": "US",
  "country_name": "United States",
  "region": "CA",
  "region_name": "California",
  "city": "Mountain View",
  "postal": "94035",
  "lat": 37.386,
  "lon": -122.084,
  "timezone": "America/Los_Angeles",
  "asn": 15169,
  "org": "Google LLC"
}

Examples

# Lookup a specific IPv4 address
dig TXT get.ip-8-8-8-8.geoip.v1.resolvedb.net +short
# "v=rdb1;s=ok;t=data;f=json;ttl=300;d={\"ip\":\"8.8.8.8\",\"country\":\"US\",...}"

# Lookup a specific IPv6 address
dig TXT get.ip-2001-4860-4860--8888.geoip.v1.resolvedb.net +short

# Lookup Cloudflare DNS
dig TXT get.ip-1-1-1-1.geoip.v1.resolvedb.net +short

Privacy Note

The server does NOT use the querier's source IP for GeoIP lookups. The client must explicitly provide the IP address they want to look up. This ensures:

• Consistent results regardless of where the query originates
• Correct behavior through DoH/DoT resolvers, VPNs, and proxies
• No privacy leakage of the client's actual IP
• Cacheable responses (same query = same result)

WebSocket Session Security (CRITICAL)

The watch operation returns a WebSocket URL for real-time updates. Session security is critical.

Session Token Format

Session tokens MUST be cryptographically secure and short-lived:

session_token = Base64URL(HMAC-SHA256(server_secret,
    tenant_id || resource_path || created_timestamp || client_ip_hash
))[0:32]  # 256-bit truncated to 32 chars

Connection Security

Handshake Requirements:

Rate Limiting:

• Maximum 10 WebSocket connections per tenant per minute
• Maximum 100 concurrent connections per tenant

Session Timeouts:

Reconnection Protocol

On disconnect, clients MUST:

1. Obtain new session token via fresh watch DNS query
2. Connect with new token (old tokens are single-use)
3. Server sends full state, not just delta

Token Single-Use Enforcement:

Session tokens are consumed on first use. Reusing a token returns:

WebSocket close code: 4401
Reason: "Session token already used"

URL Security Concerns

Session tokens in WebSocket URLs are visible in:

• Server access logs
• Browser history
• Referrer headers (if page navigates)

Mitigations:

• Short token validity (5 minutes)
• Single-use tokens
• Consider passing token via WebSocket subprotocol header: Sec-WebSocket-Protocol: resolvedb-v1, token-<session_token>

Error Codes

Pagination

For list and search operations that return multiple results, pagination is supported via cursor-based navigation.

Query Parameters

Response Fields

{
  "items": [...],
  "cursor": "eyJsYXN0X2lkIjoiMTIzIn0",
  "hasMore": true,
  "total": 523
}

Cursor Integrity (CRITICAL)

Cursors MUST be cryptographically signed to prevent manipulation attacks.

Cursor Format:

cursor = Base64URL(cursor_data) + "." + Base64URL(signature)

cursor_data = JSON({
    "last_id": "<last_item_id>",
    "tenant": "<tenant_id>",
    "query_hash": "<sha256_of_original_query_params>",
    "created": <unix_timestamp>
})

signature = HMAC-SHA256(server_secret, cursor_data)[0:16]  # 128-bit truncated

Validation Requirements:

Servers MUST:

1. Verify HMAC signature before using cursor
2. Reject cursors older than 1 hour (prevents stale enumeration)
3. Verify tenant matches authenticated user (if applicable)
4. Verify query_hash matches current query parameters (prevents cross-query cursor reuse)

Attack Prevention:

Error Response:

Invalid cursors return:

Privacy Considerations

For privacy-sensitive namespaces:

• total field SHOULD be omitted or return approximate value
• Consider capping display at "100+" to prevent exact enumeration

Example

# First page
list.limit-50.resources.hooli.v1.resolvedb.net
-> {"items":[...],"cursor":"eyJsYXN0IjoiZm9vIn0","hasMore":true,"total":150}

# Next page (cursor must fit in 63-char DNS label)
list.cursor-eyJsYXN0IjoiZm9vIn0.resources.hooli.v1.resolvedb.net
-> {"items":[...],"cursor":"eyJsYXN0IjoiYmFyIn0","hasMore":true,"total":150}

# Last page
list.cursor-eyJsYXN0IjoiYmFyIn0.resources.hooli.v1.resolvedb.net
-> {"items":[...],"hasMore":false,"total":150}

DNS Label Constraints

Cursors must fit within DNS label limits:

• Maximum 63 characters per label
• URL-safe Base64 encoding (no +, /, or =)
• For long cursors, use hash reference: cursor-h-<hash> where hash points to stored cursor state

Large Data (NULL Records)

For data >4KB, use NULL record type (up to 64KB per record):

Amplification Attack Mitigation (CRITICAL)

NULL records present significant DDoS amplification risk:

• Minimum query size: ~32 bytes
• Maximum response size: 65,536 bytes
• Amplification factor: 2,048x

Mandatory Mitigations (per RFC 5358):

Protocol Behavior:

# UDP query for large data:
Query:  get.bigdata.hooli.v1.resolvedb.net TYPE=NULL (UDP)
Response: v=rdb1;s=toolarge;err=E015;d=Use TCP for responses >4KB;tc=1

# New error code:
E015 | toolarge | Response requires TCP | Yes | Retry over TCP

Size Limits by Transport:

Rate Limits for NULL Records:

Chunking Protocol

# 1. Get manifest (includes per-chunk hashes for integrity)
get.manifest.bigfile.hooli.v1.resolvedb.net
-> {"chunks":5,"size":320000,"hash":"abc123def456789012345678901234567890123456789012345678901234","chunk_hashes":["hash0","hash1","hash2","hash3","hash4"]}

# 2. Retrieve chunks (can be parallel, format: chunk-index-total-hash)
# Hash reference MUST be at least 16 hex chars (64 bits)
get.chunk-0-5-abc123def4567890.bigfile.hooli.v1.resolvedb.net  TYPE=NULL
get.chunk-1-5-abc123def4567890.bigfile.hooli.v1.resolvedb.net  TYPE=NULL
...

# 3. Verify each chunk hash, then verify full content hash after reassembly

Chunk Integrity Verification

Clients MUST:

1. Verify each chunk's SHA-256 hash matches chunk_hashes[index] before storing
2. Verify reassembled content SHA-256 matches manifest hash
3. Reject chunks with mismatched hashes (do not retry automatically - may indicate MITM)
4. Complete all chunks within 5 minutes or restart (prevents resource exhaustion)

Encryption Wire Format

For encrypted responses (t=encrypted), the following wire format is used.

AES-256-GCM Structure

┌─────────────────────────────────────────────────────────────┐
│                    Encrypted Response                        │
├─────────────────────────────────────────────────────────────┤
│  Nonce (12 bytes)  │  Ciphertext (variable)  │  Tag (16 bytes) │
└─────────────────────────────────────────────────────────────┘

Key Derivation (CRITICAL)

Keys are derived using HKDF-SHA256 with mandatory context binding:

shared_secret = X25519(client_private, server_ephemeral_public)
               OR X25519(server_private, client_public)

encryption_key = HKDF-SHA256(
    ikm  = shared_secret,
    salt = "resolvedb-v1-encryption",
    info = context_info,  # MANDATORY - see below
    len  = 32
)

Context Binding Requirements (MANDATORY):

The context_info field MUST include all of the following to prevent key reuse attacks:

Context Construction:

context_info = concat(
    length_prefix(query_fqdn),         # 2-byte length + UTF-8 FQDN
    client_ephemeral_pubkey,           # 32 bytes
    server_ephemeral_pubkey,           # 32 bytes
    timestamp_be64,                    # 8 bytes (Unix timestamp, big-endian)
    random_nonce                       # 8 bytes (cryptographically random)
)

Security Rationale:

Without complete context binding:

• Same FQDN from different clients could derive same key
• Responses could be replayed to different sessions
• Keys could be precomputed for known FQDNs

Implementation Check:

# CORRECT: Full context binding
context = (
    len(fqdn).to_bytes(2, 'big') + fqdn.encode() +
    client_pubkey +     # 32 bytes
    server_pubkey +     # 32 bytes
    timestamp_bytes +   # 8 bytes
    random_nonce        # 8 bytes
)

# WRONG: Incomplete binding
context = fqdn.encode()  # Missing keys, timestamp, nonce

Ephemeral Key Format

The k field in encrypted responses contains the server's ephemeral X25519 public key:

Complete Example

Response:

Decoding d:

Base64 decode -> raw_bytes
nonce      = raw_bytes[0:12]      # 12 bytes
ciphertext = raw_bytes[12:-16]    # variable length
tag        = raw_bytes[-16:]      # 16 bytes

Decryption:

from cryptography.hazmat.primitives.ciphers.aead import AESGCM

# Derive shared secret from client private key and server ephemeral public
shared = x25519(client_private_key, server_ephemeral_public)
key = hkdf_sha256(shared, salt=b"resolvedb-v1-encryption", info=query_fqdn, length=32)

# Decrypt
aesgcm = AESGCM(key)
plaintext = aesgcm.decrypt(nonce, ciphertext + tag, associated_data=None)

Multi-TLD Root Server Redundancy

All four TLDs serve as active authoritative nameservers with identical data:

Client Failover

ROOT_SERVERS = ['resolvedb.com', 'resolvedb.net', 'resolvedb.org', 'resolvedb.io']

def query_with_redundancy(resource):
    # Sort by health/latency
    for tld in sorted_by_health(ROOT_SERVERS):
        try:
            result = dns_query(f"{resource}.{tld}")
            mark_healthy(tld)
            return result
        except DNSError:
            mark_unhealthy(tld)
            continue
    raise AllTLDsFailedError()

Benefits

• TLD-level failure protection
• DDoS mitigation (attack one TLD, others continue)
• Load distribution across infrastructures
• Regulatory compliance (different jurisdictions)
• Performance optimization (clients choose fastest)

Security Protocol (RDBSP)

Layer 1: DNSSEC Foundation

• ECDSA P-256 (Algorithm 13) for all zones
• Automatic key rotation (ZSK: 30 days, KSK: 365 days)
• NSEC3 with salt for authenticated denial (see parameters below)
• Clients SHOULD verify AD flag

NSEC3 Parameters (RFC 5155, RFC 9276)

NSEC3PARAM Record:

Salt Rotation:

• Rotate salt with each ZSK rotation (30 days)
• Use cryptographically random salt (minimum 64 bits)
• Zero-length salt acceptable per RFC 9276

Iteration Count Guidance (RFC 9276):

• Online signing: 0-10 iterations (performance)
• Offline signing: Up to 100 iterations acceptable
• Higher iterations provide minimal security benefit but significant CPU cost

Layer 2: Content Integrity

• SHA-256 hash verification (minimum 16 chars, full recommended)
• Ed25519 signatures for authenticity
• Unix timestamps for replay protection (5-second max tolerance)
• Cryptographic nonces (MANDATORY for authenticated requests)

Replay Protection Requirements (CRITICAL)

Timestamp Tolerance:

Nonce Requirements:

For authenticated requests (auth-* prefix), clients MUST include a nonce:

Server-Side Tracking:

Servers MUST:

1. Reject requests with ts more than 5 seconds from server time
2. Track (nonce, ts) pairs for 10 seconds (2x tolerance window)
3. Reject duplicate (nonce, ts) pairs with secviol status
4. Use constant-time comparison for nonce matching

New Error Code:

Clock Synchronization:

Clients SHOULD:

• Use NTP or similar for time synchronization
• Include RTT estimate in tolerance calculations
• Retry with fresh timestamp on E016 (but not same nonce)

Layer 3: Encryption Modes

Public (Integrity Only):

- Plaintext data
- SHA-256 hash
- Ed25519 signature
- DNSSEC transport

Symmetric (Shared Secret):

- AES-256-GCM encryption
- Pre-shared keys (out-of-band)
- Argon2id key derivation
- AEAD

Asymmetric (Public Key):

- X25519 key exchange
- ChaCha20-Poly1305 encryption
- Ephemeral keys (PFS)
- Public keys in TLSA records

Layer 4: Query Privacy (CRITICAL)

Transport Security Requirements:

Server Enforcement:

Servers MUST detect transport type and enforce requirements:

# Plaintext query to protected namespace:
v=rdb1;s=secviol;err=E014;d=Encrypted transport required (DoH/DoT)

New Error Code:

Query Privacy Measures:

• Query pattern obfuscation via QNAME minimization (RFC 9156)
• Decoy queries for statistical privacy (implementation-specific)
• Padding to fixed sizes to prevent length-based analysis

Plaintext DNS Exposure Warning:

Queries over plaintext DNS expose to all network observers:

• User identifiers in namespace paths
• Resource names being accessed
• Access timing patterns
• Query frequency

Even with hash IDs (a7f3b2 instead of hooli), traffic analysis can correlate patterns.

Authentication

# JWT in auth- parameter (hyphen prefix, not colon)
get.auth-<jwt>.resource.namespace.v1.resolvedb.net

Algorithm Requirements (CRITICAL)

Allowed Algorithms:

Forbidden Algorithms:

Algorithm Confusion Prevention:

Implementations MUST:

1. Explicit allowlist: Only process tokens with algorithms from the allowed list above
2. Pre-parse validation: Check alg header BEFORE any signature verification
3. Reject before decode: If alg is forbidden, reject immediately without attempting verification
4. Case-sensitive matching: "alg": "None" and "alg": "NONE" MUST also be rejected
5. Key type binding: RSA keys MUST only verify RS*/PS* algorithms; EC keys MUST only verify ES* algorithms

Implementation Pattern:

# BEFORE any JWT library processing:
header = base64url_decode(token.split('.')[0])
if header.get('alg') in ['none', 'None', 'NONE', 'HS256', 'HS384', 'HS512']:
    return error('secviol', 'E008', 'Forbidden algorithm')

JWT Claims Specification

Required Claims:

Optional Claims:

Example JWT Payload:

{
  "sub": "user-12345",
  "iss": "resolvedb.io",
  "aud": "resolvedb.io",
  "exp": 1704153600,
  "iat": 1704067200,
  "nbf": 1704067200,
  "jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant": "hooli",
  "scopes": ["read", "write", "list"],
  "rate_limit_tier": "pro"
}

Token Transport Constraints

DNS labels are limited to 63 characters. JWT tokens typically exceed this limit.

Solutions:

1. Token Hash Reference (REQUIRED): Store token server-side, reference by cryptographic hash

   get.auth-h-<32-hex-chars>.resource.namespace.v1.resolvedb.net

   Security Requirements:

   • Token references MUST use HMAC-SHA256 with a server-side secret key
   • Reference MUST be at least 128 bits (32 hex characters) to prevent brute-force
   • Format: auth-h-<first-32-hex-chars-of-HMAC-SHA256(server_secret, token)>
   • Server MUST maintain token-to-reference mapping with TTL matching token's exp claim
   • References MUST be invalidated when corresponding token is revoked
   • Server SHOULD rate-limit auth-h- queries to prevent enumeration attacks

2. Short-Lived Tokens: Use compact tokens with minimal claims (max 5 minutes validity)

3. Multi-Label Split: Spread token across labels - NOT RECOMMENDED due to:

   • Increased attack surface (multiple labels to intercept)
   • Complex reassembly logic prone to implementation errors
   • No integrity protection across labels

Recommended Pattern: Use the HTTP API to exchange a full JWT for a cryptographically-signed token reference, then use that reference in DNS queries. The reference exchange endpoint MUST require TLS 1.3+.

DNS Compliance (RFC 1035/1123)

Absolute Limits

• Max FQDN: 253 characters (excluding trailing dot, per RFC 1035 Section 2.3.4)
• Max label: 63 characters
• Max labels: 127 levels
• Valid chars: a-z, A-Z, 0-9, - (hyphen, not at label edges)

Important: Colons (:) are NOT valid DNS characters. UQRP uses hyphens (-) for encoding prefixes (e.g., b64- not b64:).

Case Normalization (CRITICAL)

Per RFC 1035 Section 2.3.3, DNS names are case-insensitive. Implementations MUST normalize consistently to prevent security issues.

Normalization Requirements:

Security Rationale:

Without consistent normalization, attackers can exploit case differences:

# Attack: Cache poisoning via case confusion
1. Victim caches response for: get.data.VICTIM.v1.resolvedb.net
2. Cache key uses: get.data.victim.v1.resolvedb.net (normalized)
3. Attacker queries with different case: get.data.Victim.v1.resolvedb.net
4. If parser extracts "Victim" but cache uses "victim", cross-user data leak

# Defense: Normalize BEFORE any extraction
namespace = extracted_namespace.to_lowercase()  # FIRST

Implementation Pattern:

// CORRECT: Normalize immediately at parse
fn parse_query(qname: &str) -> Result<ParsedQuery> {
    let normalized = qname.to_lowercase(); // FIRST OPERATION
    let parts: Vec<&str> = normalized.split('.').collect();
    // All subsequent operations use normalized form
}

// WRONG: Normalize only at cache time
fn get_cache_key(qname: &str) -> String {
    qname.to_lowercase() // TOO LATE - parser may have used original case
}

Length Budget

Base domain:     resolvedb.net           (12 chars)
Tenant:          hooli                   (4-10 chars)
Version:         v1                      (2 chars)
Separators:                              (3-10 chars)
Safety margin:                           (10 chars)
─────────────────────────────────────────────────────
Reserved:                                (~35 chars)
Available for data:                      (~218 chars)

Fallback Strategies

1. Hash Reference: Store full data, query by hash
2. Multi-Query: Split across queries
3. Compression: Dictionary for common patterns
4. Indirect: Short reference to full data

Rate Limits

Rate Limit Normalization (CRITICAL)

Rate limiting MUST use normalized queries to prevent bypass via case variations.

Normalization Before Rate Check:

# These MUST count as the SAME query for rate limiting:
get.data.VICTIM.v1.resolvedb.net
get.data.victim.v1.resolvedb.net
get.data.Victim.v1.resolvedb.net
GET.data.victim.v1.resolvedb.net  # Operation case

Rate Limit Key Construction:

rate_key = hash(
    source_ip_prefix,              # /24 for IPv4, /48 for IPv6
    normalized_qname.to_lowercase(),
    qtype,
    qclass
)

Separate Buckets (Do NOT Combine):

Bypass Prevention:

Attackers may attempt bypass via:

1. Case variations - Mitigated by normalization
2. Multiple query types - Separate buckets prevent mixing
3. Distributed sources - /24 aggregation limits effectiveness
4. Authenticated token rotation - Per-tenant limits apply

Rate Limit Response:

Pluggable Provider Protocol (PPP)

Services can be implemented via MCPs or custom backends:

class ResolveDBProvider:
    name: str
    version: str
    capabilities: ProviderCapabilities

    def can_handle(self, query: DNSQuery) -> bool
    def execute(self, query: DNSQuery) -> DNSResponse
    def health_check(self) -> HealthStatus

Service Discovery:

_services.registry.resolvedb.net    TXT  "weather.v1,stock.v1,news.v1"
_meta.weather.v1.registry           TXT  "provider=OpenWeather;sla=99.9"
_health.weather.v1.registry         TXT  "status=healthy;latency=15ms"

Location-Based Queries

Following the Privacy by Design principle, location-based queries REQUIRE explicit location parameters. The server does NOT infer location from the client's IP address.

Location Parameter Formats

# Named location (city, region)
get.city-newyork.weather.public.v1.resolvedb.net

# Coordinates via geo- prefix (decimals use 'd' separator)
# Format: lat-<lat>.lon-<lon> where decimals use 'd' separator
get.lat-40d7128.lon--74d0060.weather.public.v1.resolvedb.net
#                   ^^ double hyphen for negative longitude

# Coordinates via Base64-encoded JSON
# {"lat":40.7128,"lon":-74.0060} -> eyJsYXQiOjQwLjcxMjgsImxvbiI6LTc0LjAwNjB9
get.b64-eyJsYXQiOjQwLjcxMjgsImxvbiI6LTc0LjAwNjB9.weather.public.v1.resolvedb.net

Why Explicit Location?

Note: Colons (:) are not valid in DNS labels per RFC 1035. All parameters requiring special characters must use Base64 encoding or DNS-safe character substitution.

EDNS Client Subnet (ECS) Handling (RFC 7871)

Privacy Implications:

ECS exposes client subnet information to authoritative servers. This creates privacy concerns:

• Client location disclosed without explicit consent
• Cached responses may leak location to subsequent queries
• Third-party observers can correlate IP ranges to locations

Server Requirements:

Scope Prefix Behavior:

Servers MUST include SCOPE PREFIX-LENGTH in ECS responses to indicate caching granularity:

# Query includes ECS with /24 prefix
# Server responds with /16 scope (less specific = broader caching)
Client: ECS 192.0.2.0/24
Server: ECS 192.0.0.0/16 SCOPE 16

# Cached response valid for all 192.0.x.x clients

Privacy Mode (ECS=0):

Clients MAY send ECS with SOURCE PREFIX-LENGTH=0 to indicate privacy preference:

• Server MUST NOT use client subnet for response
• Server MUST respond with SCOPE PREFIX-LENGTH=0
• Response is cached globally (no location variance)

# Privacy mode query
Client: ECS 0.0.0.0/0 (SOURCE=0)
Server: ECS 0.0.0.0/0 SCOPE=0

GeoIP Privacy Considerations:

1. geoip operation responses MUST use short TTL (30-60 seconds)
2. GeoIP should NOT be served via shared recursive resolvers
3. For accurate, privacy-preserving geolocation, clients should query authoritative directly over DoH
4. The geoip operation SHOULD NOT cache at intermediate resolvers

Cache Scope Pollution Prevention:

Implementations MUST separate cache entries by ECS scope:

Cache Key = (QNAME, QTYPE, QCLASS, ECS_SCOPE_PREFIX)

# Different cache entries:
weather.public.v1.resolvedb.net:TXT:IN:192.0.0.0/16
weather.public.v1.resolvedb.net:TXT:IN:198.51.0.0/16
weather.public.v1.resolvedb.net:TXT:IN:GLOBAL  # ECS=0 response

TTL Cache Delegation

ResolveDB's core scalability advantage: leveraging the global DNS caching infrastructure to achieve massive query reduction.

RFC References: TTL semantics per RFC 1035 Section 3.2.1, negative caching per RFC 2308, stale serving per RFC 8767.

The Caching Multiplier

When ResolveDB returns a response with ttl=3600, every resolver in the DNS hierarchy caches that response independently:

┌─────────────────────────────────────────────────────────────────┐
│                    DNS CACHING HIERARCHY                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐                                               │
│  │   Browser    │  TTL respected per response                   │
│  │   DNS Cache  │  (Chrome, Firefox, Safari cache DNS)          │
│  └──────┬───────┘                                               │
│         │ cache miss                                            │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │   OS DNS     │  System resolver cache                        │
│  │   Cache      │  (macOS, Windows, Linux systemd-resolved)     │
│  └──────┬───────┘                                               │
│         │ cache miss                                            │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │  Corporate   │  Serves entire organization                   │
│  │  DNS Server  │  (1000s of users share this cache)            │
│  └──────┬───────┘                                               │
│         │ cache miss                                            │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │  ISP         │  Serves millions of subscribers               │
│  │  Recursive   │  (Comcast, AT&T, regional ISPs)               │
│  └──────┬───────┘                                               │
│         │ cache miss                                            │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │  Public DNS  │  Global scale (8.8.8.8, 1.1.1.1)             │
│  │  (optional)  │  Serves tens of millions                      │
│  └──────┬───────┘                                               │
│         │ cache miss                                            │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │  ResolveDB   │  <--- ONLY SEES CACHE MISSES                  │
│  │ Authoritative│                                               │
│  └──────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Example: If 10,000 users behind a corporate DNS query weather.public.v1.resolvedb.net with ttl=3600:

• Traditional API: 10,000 requests/hour to origin
• ResolveDB: 1 request/hour (all others served from corporate DNS cache)

Key insight: ResolveDB query volume scales with:

• (Number of UNIQUE queries) x (1 / TTL)

NOT with total number of clients or total request volume.

TTL Classes

Server assigns TTL based on data volatility classification:

Operation TTL Defaults

TTL Selection Guidelines

For API Consumers:

1. Static configuration: Use stable (24h) or include version in query path
2. User data: Use dynamic (5min) - accept predictable staleness window
3. Real-time feeds: Use volatile (30-60s) or switch to streaming (watch)
4. Content-addressed: Use immutable (7 days) for h-<hash> queries

Special Cases:

Authenticated Query Cache Exclusion (CRITICAL)

Authenticated queries MUST NOT be cached to prevent cross-user data leakage.

Detection Requirements:

Implementations MUST detect authenticated queries through BOTH methods:

Fail-Secure Behavior:

fn is_authenticated_query(query: &DNSQuery) -> bool {
    // PRIMARY: Parse the query structure
    match parse_resolvedb_query(query) {
        Ok(parsed) => parsed.auth_token.is_some(),
        Err(_) => true,  // FAIL SECURE: If parsing fails, assume authenticated
    }
}

Security Rationale:

Without strict auth detection:

1. Encoded auth tokens (b64-<token-with-auth-inside>) bypass string matching
2. Malformed queries may cache and serve to unauthorized users
3. Cross-user cache poisoning becomes possible

Cache Key Requirements for Authenticated Queries:

If authenticated responses MUST be cached (e.g., for performance):

• Cache key MUST include full token hash or user identifier
• Cache entries MUST be isolated per authenticated session
• TTL MUST NOT exceed token expiration minus clock skew margin

Negative Caching (RFC 2308)

ResolveDB returns negative responses in two forms:

Both responses include the SOA record in the authority section (required for caching per RFC 2308 Section 3). Negative caching prevents repeated queries for non-existent resources and defends against DNS water torture attacks.

TTL=0 Behavior Notes

TTL=0 signals "do not cache" per RFC 1035, but resolver implementations vary:

For truly uncacheable operations (put, delete, errors), TTL=0 is correct but clients should not assume zero latency for repeated queries. Write confirmations should use response signatures for verification regardless of caching.

Resolver TTL Capping

Some public resolvers cap maximum TTL values:

The immutable class (7 days) may be capped to 1 day by some resolvers. For hash-addressed content (h-<hash>), this is acceptable since re-queries return identical data.

GeoIP/ECS Considerations

When responses vary by client location using EDNS Client Subnet (RFC 7871), caching becomes scope-limited. A response served to NYC clients is not cacheable for LA clients, reducing the caching multiplier but maintaining correctness.

Implementation Status

Protocol Evolution

Version Negotiation

Negotiation Process:

1. Client queries with preferred version: get.weather.public.v2.resolvedb.net
2. If server doesn't support v2, respond with redirect: v=rdb1;s=redirect;supported=v1;d=get.weather.public.v1.resolvedb.net
3. Client retries with supported version

Anti-Downgrade Protection (CRITICAL):

Attackers may force clients to use older, vulnerable protocol versions:

Server Health Includes Version Info:

Client Behavior:

def negotiate_version(preferred: str, server_supported: list) -> str:
    # Check minimum version requirement
    if server_min_version > client_minimum_acceptable:
        raise VersionError("Server requires newer client")

    # Only downgrade one major version
    pref_major = int(preferred[1:])
    for v in sorted(server_supported, reverse=True):
        v_major = int(v[1:])
        if v_major >= pref_major - 1:  # Max 1 version downgrade
            return v

    raise VersionError("No acceptable version available")

Backward Compatibility Rules

Deprecation

Deprecation Timeline:

• Deprecation announcement: 6 months before sunset
• Warning responses: 3 months before sunset (include deprecation=true in responses)
• Sunset: Return redirect to new version

Domain Portfolio

Revision History

This specification is under active development. For change history, see the git log.