dns-tools/openapi.yaml at main · stack127labs/dns-tools · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
openapi: 3.1.0
info:
  title: DNS Tools API
  version: 1.0.0
  description: Same-origin APIs used by the self-hosted DNS Tools pages.
  license:
    name: MIT
servers:
  - url: http://localhost:1273
paths:
  /api/health:
    get:
      summary: Check process liveness
      responses:
        "200":
          description: The Next.js process is ready.
          content:
            application/json:
              schema:
                type: object
                required: [status, service]
                properties:
                  status: { const: ok }
                  service: { const: dns-tools }
  /api/dns/lookup:
    post:
      summary: Look up one record type or the defined All bundle
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LookupRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" } }
  /api/dns/trace:
    post:
      summary: Follow one DNS question from the root servers
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RecordRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" }, "504": { $ref: "#/components/responses/Error" } }
  /api/dns/change-checker:
    post:
      summary: Compare authoritative and recursive DNS answers
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ChangeRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" }, "504": { $ref: "#/components/responses/Error" } }
  /api/dns/nameserver-checker:
    post:
      summary: Check parent and child nameserver delegation
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NameRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" }, "504": { $ref: "#/components/responses/Error" } }
  /api/dns/dnssec-checker:
    post:
      summary: Validate one DNSSEC answer from the root trust anchor
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DnssecRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" }, "504": { $ref: "#/components/responses/Error" } }
  /api/dns/soa-checker:
    post:
      summary: Compare SOA values across authoritative nameservers
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NameRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" }, "504": { $ref: "#/components/responses/Error" } }
  /api/dns/caa-checker:
    post:
      summary: Find the effective CAA policy for a certificate name
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NameRequest" }
      responses: { "200": { $ref: "#/components/responses/ToolResult" }, "400": { $ref: "#/components/responses/Error" }, "403": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" }, "504": { $ref: "#/components/responses/Error" } }
components:
  responses:
    ToolResult:
      description: Normalized tool result. The exact TypeScript result models live under lib/dns.
      headers:
        Cache-Control: { schema: { type: string }, description: Always no-store. }
        X-RateLimit-Remaining: { schema: { type: integer } }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ToolResult" }
    Error:
      description: Validation, policy, rate-limit, or timeout response.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorResponse" }
  schemas:
    NameRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name: { type: string, minLength: 1 }
    RecordRequest:
      type: object
      additionalProperties: false
      required: [name, recordType]
      properties:
        name: { type: string, minLength: 1 }
        recordType: { $ref: "#/components/schemas/ForwardRecordType" }
    DnssecRequest:
      allOf:
        - { $ref: "#/components/schemas/RecordRequest" }
    ChangeRequest:
      type: object
      additionalProperties: false
      required: [name, recordType]
      properties:
        name: { type: string, minLength: 1 }
        recordType: { $ref: "#/components/schemas/ForwardRecordType" }
        expectedAnswer: { type: string }
    LookupRequest:
      type: object
      additionalProperties: false
      required: [name, selection, resolver]
      properties:
        name: { type: string, minLength: 1 }
        selection:
          enum: [all, A, AAAA, CNAME, MX, NS, TXT, CAA, SOA, SRV, DS, DNSKEY, PTR]
        resolver:
          enum: [cloudflare, google, quad9, opendns, adguard, controld, yandex, authoritative]
    ForwardRecordType:
      enum: [A, AAAA, CNAME, MX, NS, TXT, CAA, SOA, SRV, DS, DNSKEY]
    NullableBoolean:
      type: [boolean, "null"]
    NormalizedRecord:
      type: object
      required: [name, type, data, resolverTtlSeconds]
      properties:
        name: { type: string }
        type: { type: string }
        data: {}
        resolverTtlSeconds: { type: [integer, "null"], minimum: 0 }
      additionalProperties: true
    RawDnsResponse:
      type: [object, "null"]
      additionalProperties: true
    ToolResult:
      type: object
      description: Tool-specific normalized evidence. Optional provider fields remain nullable and raw responses remain attached.
      properties:
        checkedAt: { type: string, format: date-time }
        durationMs: { type: number, minimum: 0 }
        query: { type: object, additionalProperties: true }
        records:
          type: array
          items: { $ref: "#/components/schemas/NormalizedRecord" }
        rawResponse: { $ref: "#/components/schemas/RawDnsResponse" }
      additionalProperties: true
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string }
            message: { type: string }