# LiteDNS Agent Skill

Use LiteDNS to resolve any public domain from an explicit China (`cn`) or
overseas (`us`) vantage. The same API key works for the JSON API and DoH.
This document is written for AI agents and scripts.

## 1. Install

No SDK is required. Use curl or any HTTPS client. Create an API key in the
console first:

- Console: https://dns.litelake.cn/console
- International console: https://dns.litelake.com/en/console

Store the key in an environment variable, never in shared logs:

```sh
export LITEDNS_API_KEY="<prefix>.<secret>"
export LITEDNS_BASE="https://dns.litelake.cn"
```

## 2. Configure

| Item | Value |
| --- | --- |
| Base URL (China) | https://dns.litelake.cn |
| Base URL (international) | https://dns.litelake.com |
| JSON endpoint | `POST /api/open/resolve` |
| DoH endpoint | `GET/POST /api/open/doh/{region}/{apikey}` |
| Regions | `cn`, `us` |
| Record types | A, AAAA, CNAME, TXT, MX, NS, SOA |
| Authentication | `X-API-Key` header (JSON) or key in URL path (DoH) |

The region is explicit. There is no GeoDNS auto-selection and no cross-region
fallback. Quota belongs to the account: every key, both protocols and both
regions share one allowance.

## 3. JSON API

```sh
curl -s "$LITEDNS_BASE/api/open/resolve" \
  -H "X-API-Key: $LITEDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","type":"A","region":"cn"}'
```

Successful responses use the common envelope and put the DNS result in
`data`:

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "status": "NOERROR",
    "rcode": 0,
    "answers": [
      { "name": "example.com.", "type": "A", "ttl": 300, "data": "93.184.216.34" }
    ],
    "provenance": {
      "region": "cn",
      "exec_region": "cn",
      "upstream": "223.5.5.5",
      "cache": "miss",
      "latency_ms": 23
    }
  }
}
```

Reading the answer:

- `status=NOERROR` and a non-empty `answers` array: resolved.
- `status=NXDOMAIN` with an authority SOA: the name does not exist.
- `status=SERVFAIL` or a failed request: treat as unknown, retry later.

## 4. DoH (RFC 8484)

GET with base64url (no padding):

```sh
curl -s -H "Accept: application/dns-message" \
  "$LITEDNS_BASE/api/open/doh/cn/$LITEDNS_API_KEY?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB" \
  --output answer.bin
```

POST with wire bytes:

```sh
curl -s -X POST \
  -H "Content-Type: application/dns-message" \
  --data-binary @query.bin \
  "$LITEDNS_BASE/api/open/doh/cn/$LITEDNS_API_KEY" \
  --output answer.bin
```

Valid DNS answers, including NXDOMAIN and SERVFAIL, are returned with HTTP 200
and `Content-Type: application/dns-message`. Inspect provenance through the
`X-LiteDNS-Region`, `X-LiteDNS-Upstream` and `X-LiteDNS-Cache` response
headers. Request bodies are limited to 64 KB.

DoH client configuration:

| Client | Supported | Note |
| --- | --- | --- |
| Firefox custom DoH | Yes | Full keyed URL |
| Chrome / Edge secure DNS | Yes | URI template may include a path |
| iOS / macOS profile | Yes | Full URL in the DNS settings payload |
| curl / scripts | Yes | GET or POST |
| Android Private DNS | No | Hostname only; cannot carry a key path |

## 5. Errors

| HTTP | Meaning | Action |
| --- | --- | --- |
| 400 | Invalid domain, type or message format | Fix the request |
| 401 | Missing or invalid API key | Check the key |
| 403 | Key revoked, tier unavailable or scope not allowed | Issue a new key or upgrade |
| 404 | Unknown region | Use `cn` or `us` |
| 406 | Accept does not allow `application/dns-message` | Send the correct Accept header |
| 413 | Request body exceeds 64 KB | Reduce the query or use POST |
| 415 | Unsupported media type | Send `application/dns-message` |
| 429 | Account quota exceeded | Wait for the `Retry-After` interval |
| 504 | All upstreams failed and no cache could answer | Retry later |

For DoH, a 4xx status means no DNS answer was produced. A DNS-level SERVFAIL
is still HTTP 200 with the wire response preserved.

## 6. Safety

- Keep the API key in an environment variable or secret store.
- The key appears in the DoH URL path by design; avoid printing full URLs in
  shared logs.
- Do not use LiteDNS for domain scanning, tunnelling or resale.