{"openapi":"3.0.3","info":{"title":"BlockAds DNS Leak Check Open API","version":"1.0.0","description":"Open REST API for detecting DNS leaks, EDNS Client Subnet (ECS) exposure, and inspecting DNS resolvers. Powered by brianshea2/addr.tools.","contact":{"name":"BlockAds Team","url":"https://edge-dns.pwhs.app"},"x-powered-by":{"name":"brianshea2/addr.tools","url":"https://github.com/brianshea2/addr.tools","description":"possibly useful tools for the Internet","author":"Brian Shea","repo":"https://github.com/brianshea2/addr.tools"}},"servers":[{"url":"https://edge-dns.pwhs.app","description":"BlockAds Edge Serverless API"}],"paths":{"/api/dns-leak/init":{"get":{"summary":"Initialize a DNS leak test session","description":"Generates a unique 8-character hex session ID, probe subdomains to resolve, real-time WebSocket watcher URL, and client IP/ASN identity.","responses":{"200":{"description":"Session successfully initialized","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"sessionId":{"type":"string","example":"3f82a1b9"},"wsUrl":{"type":"string","example":"wss://ws.dnscheck.tools/watch/3f82a1b9"},"watchWebUrl":{"type":"string","example":"https://dnscheck.tools/watch/3f82a1b9"},"probeDomains":{"type":"array","items":{"type":"string"},"example":["a.3f82a1b9-nullip.test.dnscheck.tools","b.3f82a1b9-nullip.test.dnscheck.tools","c.3f82a1b9-nullip.test.dnscheck.tools","d.3f82a1b9-nullip.test.dnscheck.tools"]},"dnssecSuite":{"type":"object","description":"Full suite of DNSSEC cryptographic validation test domains (ECDSA P-256, P-384, Ed25519, MLDSA44 across badsig, expiredsig, nosig)"},"dualStackEndpoints":{"type":"object","properties":{"ipv4":{"type":"string","example":"https://myipv4.addr.tools/plain"},"ipv6":{"type":"string","example":"https://myipv6.addr.tools/plain"}}},"stunServers":{"type":"array","items":{"type":"string"},"example":["stun:myip.addr.tools:3478","stun:stun.l.google.com:19302"]},"client":{"type":"object","properties":{"ip":{"type":"string","example":"14.161.20.10"},"country":{"type":"string","example":"VN"},"city":{"type":"string","example":"Ho Chi Minh City"},"asn":{"type":"integer","example":45899},"asOrg":{"type":"string","example":"VNPT Corp"},"colo":{"type":"string","example":"SGN"}}},"poweredBy":{"type":"object","properties":{"name":{"type":"string","example":"brianshea2/addr.tools"},"url":{"type":"string","example":"https://github.com/brianshea2/addr.tools"}}}}}}}}}}},"/api/dns-leak/myip":{"get":{"summary":"Get current client network identity","description":"Returns the calling client's public IP, ASN, ISP name, country, city, and Cloudflare Edge colocation point.","responses":{"200":{"description":"Client identity info","content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","example":"14.161.20.10"},"country":{"type":"string","example":"VN"},"city":{"type":"string","example":"Ho Chi Minh City"},"asn":{"type":"integer","example":45899},"asOrg":{"type":"string","example":"VNPT Corp"},"colo":{"type":"string","example":"SGN"}}}}}}}}},"/api/dns-leak/enrich":{"get":{"summary":"Enrich a resolver IP address with Geo, Org & PTR","description":"Performs reverse DNS (PTR) lookup and ISP/Geo resolution for any given IP address via addr.tools.","parameters":[{"name":"ip","in":"query","required":true,"schema":{"type":"string"},"description":"The IP address of the DNS resolver to inspect","example":"1.1.1.1"}],"responses":{"200":{"description":"Enriched resolver details","content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","example":"1.1.1.1"},"org":{"type":"string","example":"Cloudflare, Inc."},"country":{"type":"string","example":"US"},"city":{"type":"string","example":"San Francisco"},"ptr":{"type":"string","nullable":true,"example":"one.one.one.one"},"ns":{"type":"string","nullable":true,"example":"cruz.ns.cloudflare.com"},"poweredBy":{"type":"object"}}}}}}}}},"/api/dns-leak/analyze":{"post":{"summary":"Evaluate DNS resolver list for leaks","description":"Takes client ASN and a list of detected resolver IPs, and determines whether an ISP leak or EDNS Client Subnet (ECS) exposure exists.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientAsn":{"type":"integer","example":45899},"resolvers":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string","example":"1.1.1.1"},"clientSubnet":{"type":"string","nullable":true,"example":null}}}}}}}}},"responses":{"200":{"description":"Comprehensive DNS leak verdict and breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"verdict":{"type":"string","enum":["secure","leak_detected","ecs_leak"]},"isLeak":{"type":"boolean","example":false},"hasEcsLeak":{"type":"boolean","example":false},"message":{"type":"string"},"client":{"type":"object"},"resolvers":{"type":"array","items":{"type":"object"}},"poweredBy":{"type":"object"}}}}}}}}}}}