@serve.zone/dcrouter-apiclient 32.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (200) hide show
  1. package/dist_ts_apiclient/classes.apitoken.d.ts +41 -0
  2. package/dist_ts_apiclient/classes.apitoken.js +115 -0
  3. package/dist_ts_apiclient/classes.certificate.d.ts +57 -0
  4. package/dist_ts_apiclient/classes.certificate.js +69 -0
  5. package/dist_ts_apiclient/classes.config.d.ts +7 -0
  6. package/dist_ts_apiclient/classes.config.js +11 -0
  7. package/dist_ts_apiclient/classes.dcrouterapiclient.d.ts +54 -0
  8. package/dist_ts_apiclient/classes.dcrouterapiclient.js +97 -0
  9. package/dist_ts_apiclient/classes.email.d.ts +30 -0
  10. package/dist_ts_apiclient/classes.email.js +52 -0
  11. package/dist_ts_apiclient/classes.gatewayclient.d.ts +28 -0
  12. package/dist_ts_apiclient/classes.gatewayclient.js +52 -0
  13. package/dist_ts_apiclient/classes.logs.d.ts +28 -0
  14. package/dist_ts_apiclient/classes.logs.js +69 -0
  15. package/dist_ts_apiclient/classes.radius.d.ts +59 -0
  16. package/dist_ts_apiclient/classes.radius.js +95 -0
  17. package/dist_ts_apiclient/classes.remoteingress.d.ts +66 -0
  18. package/dist_ts_apiclient/classes.remoteingress.js +164 -0
  19. package/dist_ts_apiclient/classes.route.d.ts +39 -0
  20. package/dist_ts_apiclient/classes.route.js +125 -0
  21. package/dist_ts_apiclient/classes.stats.d.ts +47 -0
  22. package/dist_ts_apiclient/classes.stats.js +38 -0
  23. package/dist_ts_apiclient/classes.testing.d.ts +65 -0
  24. package/dist_ts_apiclient/classes.testing.js +120 -0
  25. package/dist_ts_apiclient/index.d.ts +12 -0
  26. package/dist_ts_apiclient/index.js +16 -0
  27. package/dist_ts_apiclient/plugins.d.ts +4 -0
  28. package/dist_ts_apiclient/plugins.js +6 -0
  29. package/dist_ts_interfaces/data/acme-config.d.ts +23 -0
  30. package/dist_ts_interfaces/data/acme-config.js +2 -0
  31. package/dist_ts_interfaces/data/auth.d.ts +8 -0
  32. package/dist_ts_interfaces/data/auth.js +2 -0
  33. package/dist_ts_interfaces/data/config-events.d.ts +34 -0
  34. package/dist_ts_interfaces/data/config-events.js +8 -0
  35. package/dist_ts_interfaces/data/dns-authority.d.ts +98 -0
  36. package/dist_ts_interfaces/data/dns-authority.js +26 -0
  37. package/dist_ts_interfaces/data/dns-provider.d.ts +136 -0
  38. package/dist_ts_interfaces/data/dns-provider.js +41 -0
  39. package/dist_ts_interfaces/data/dns-record.d.ts +48 -0
  40. package/dist_ts_interfaces/data/dns-record.js +2 -0
  41. package/dist_ts_interfaces/data/domain.d.ts +35 -0
  42. package/dist_ts_interfaces/data/domain.js +2 -0
  43. package/dist_ts_interfaces/data/email-domain.d.ts +177 -0
  44. package/dist_ts_interfaces/data/email-domain.js +2 -0
  45. package/dist_ts_interfaces/data/email-settings.d.ts +68 -0
  46. package/dist_ts_interfaces/data/email-settings.js +2 -0
  47. package/dist_ts_interfaces/data/index.d.ts +18 -0
  48. package/dist_ts_interfaces/data/index.js +19 -0
  49. package/dist_ts_interfaces/data/remoteingress.d.ts +181 -0
  50. package/dist_ts_interfaces/data/remoteingress.js +15 -0
  51. package/dist_ts_interfaces/data/route-management.d.ts +270 -0
  52. package/dist_ts_interfaces/data/route-management.js +130 -0
  53. package/dist_ts_interfaces/data/security-policy.d.ts +32 -0
  54. package/dist_ts_interfaces/data/security-policy.js +2 -0
  55. package/dist_ts_interfaces/data/smtp-account.d.ts +50 -0
  56. package/dist_ts_interfaces/data/smtp-account.js +9 -0
  57. package/dist_ts_interfaces/data/stats.d.ts +283 -0
  58. package/dist_ts_interfaces/data/stats.js +2 -0
  59. package/dist_ts_interfaces/data/target-profile.d.ts +30 -0
  60. package/dist_ts_interfaces/data/target-profile.js +2 -0
  61. package/dist_ts_interfaces/data/testing.d.ts +191 -0
  62. package/dist_ts_interfaces/data/testing.js +20 -0
  63. package/dist_ts_interfaces/data/vpn.d.ts +65 -0
  64. package/dist_ts_interfaces/data/vpn.js +2 -0
  65. package/dist_ts_interfaces/data/workhoster.d.ts +63 -0
  66. package/dist_ts_interfaces/data/workhoster.js +2 -0
  67. package/dist_ts_interfaces/index.d.ts +5 -0
  68. package/dist_ts_interfaces/index.js +8 -0
  69. package/dist_ts_interfaces/plugins.d.ts +2 -0
  70. package/dist_ts_interfaces/plugins.js +4 -0
  71. package/dist_ts_interfaces/requests/acme-config.d.ts +42 -0
  72. package/dist_ts_interfaces/requests/acme-config.js +2 -0
  73. package/dist_ts_interfaces/requests/admin.d.ts +69 -0
  74. package/dist_ts_interfaces/requests/admin.js +3 -0
  75. package/dist_ts_interfaces/requests/api-tokens.d.ts +85 -0
  76. package/dist_ts_interfaces/requests/api-tokens.js +2 -0
  77. package/dist_ts_interfaces/requests/certificate.d.ts +87 -0
  78. package/dist_ts_interfaces/requests/certificate.js +5 -0
  79. package/dist_ts_interfaces/requests/combined.stats.d.ts +29 -0
  80. package/dist_ts_interfaces/requests/combined.stats.js +2 -0
  81. package/dist_ts_interfaces/requests/config-events.d.ts +35 -0
  82. package/dist_ts_interfaces/requests/config-events.js +4 -0
  83. package/dist_ts_interfaces/requests/config.d.ts +93 -0
  84. package/dist_ts_interfaces/requests/config.js +3 -0
  85. package/dist_ts_interfaces/requests/dns-authority.d.ts +80 -0
  86. package/dist_ts_interfaces/requests/dns-authority.js +3 -0
  87. package/dist_ts_interfaces/requests/dns-providers.d.ts +117 -0
  88. package/dist_ts_interfaces/requests/dns-providers.js +2 -0
  89. package/dist_ts_interfaces/requests/dns-records.d.ts +89 -0
  90. package/dist_ts_interfaces/requests/dns-records.js +2 -0
  91. package/dist_ts_interfaces/requests/domains.d.ts +142 -0
  92. package/dist_ts_interfaces/requests/domains.js +2 -0
  93. package/dist_ts_interfaces/requests/email-domains.d.ts +154 -0
  94. package/dist_ts_interfaces/requests/email-domains.js +2 -0
  95. package/dist_ts_interfaces/requests/email-ops.d.ts +211 -0
  96. package/dist_ts_interfaces/requests/email-ops.js +3 -0
  97. package/dist_ts_interfaces/requests/email-settings.d.ts +26 -0
  98. package/dist_ts_interfaces/requests/email-settings.js +2 -0
  99. package/dist_ts_interfaces/requests/index.d.ts +29 -0
  100. package/dist_ts_interfaces/requests/index.js +30 -0
  101. package/dist_ts_interfaces/requests/logs.d.ts +43 -0
  102. package/dist_ts_interfaces/requests/logs.js +4 -0
  103. package/dist_ts_interfaces/requests/network-targets.d.ts +102 -0
  104. package/dist_ts_interfaces/requests/network-targets.js +2 -0
  105. package/dist_ts_interfaces/requests/radius.d.ts +280 -0
  106. package/dist_ts_interfaces/requests/radius.js +3 -0
  107. package/dist_ts_interfaces/requests/realtime.d.ts +38 -0
  108. package/dist_ts_interfaces/requests/realtime.js +12 -0
  109. package/dist_ts_interfaces/requests/remoteingress.d.ts +162 -0
  110. package/dist_ts_interfaces/requests/remoteingress.js +3 -0
  111. package/dist_ts_interfaces/requests/route-management.d.ts +147 -0
  112. package/dist_ts_interfaces/requests/route-management.js +2 -0
  113. package/dist_ts_interfaces/requests/security-policy.d.ts +105 -0
  114. package/dist_ts_interfaces/requests/security-policy.js +2 -0
  115. package/dist_ts_interfaces/requests/smtp-accounts.d.ts +125 -0
  116. package/dist_ts_interfaces/requests/smtp-accounts.js +2 -0
  117. package/dist_ts_interfaces/requests/source-profiles.d.ts +102 -0
  118. package/dist_ts_interfaces/requests/source-profiles.js +2 -0
  119. package/dist_ts_interfaces/requests/stats.d.ts +196 -0
  120. package/dist_ts_interfaces/requests/stats.js +4 -0
  121. package/dist_ts_interfaces/requests/target-profiles.d.ts +105 -0
  122. package/dist_ts_interfaces/requests/target-profiles.js +2 -0
  123. package/dist_ts_interfaces/requests/testing.d.ts +169 -0
  124. package/dist_ts_interfaces/requests/testing.js +2 -0
  125. package/dist_ts_interfaces/requests/users.d.ts +53 -0
  126. package/dist_ts_interfaces/requests/users.js +3 -0
  127. package/dist_ts_interfaces/requests/vpn.d.ts +188 -0
  128. package/dist_ts_interfaces/requests/vpn.js +3 -0
  129. package/dist_ts_interfaces/requests/workhoster.d.ts +79 -0
  130. package/dist_ts_interfaces/requests/workhoster.js +2 -0
  131. package/license +21 -0
  132. package/package.json +67 -0
  133. package/readme.md +218 -0
  134. package/ts_apiclient/classes.apitoken.ts +157 -0
  135. package/ts_apiclient/classes.certificate.ts +124 -0
  136. package/ts_apiclient/classes.config.ts +17 -0
  137. package/ts_apiclient/classes.dcrouterapiclient.ts +138 -0
  138. package/ts_apiclient/classes.email.ts +77 -0
  139. package/ts_apiclient/classes.gatewayclient.ts +110 -0
  140. package/ts_apiclient/classes.logs.ts +91 -0
  141. package/ts_apiclient/classes.radius.ts +180 -0
  142. package/ts_apiclient/classes.remoteingress.ts +217 -0
  143. package/ts_apiclient/classes.route.ts +166 -0
  144. package/ts_apiclient/classes.stats.ts +111 -0
  145. package/ts_apiclient/classes.testing.ts +152 -0
  146. package/ts_apiclient/index.ts +17 -0
  147. package/ts_apiclient/plugins.ts +10 -0
  148. package/ts_apiclient/readme.md +218 -0
  149. package/ts_interfaces/data/acme-config.ts +23 -0
  150. package/ts_interfaces/data/auth.ts +8 -0
  151. package/ts_interfaces/data/config-events.ts +38 -0
  152. package/ts_interfaces/data/dns-authority.ts +106 -0
  153. package/ts_interfaces/data/dns-provider.ts +174 -0
  154. package/ts_interfaces/data/dns-record.ts +50 -0
  155. package/ts_interfaces/data/domain.ts +36 -0
  156. package/ts_interfaces/data/email-domain.ts +206 -0
  157. package/ts_interfaces/data/email-settings.ts +75 -0
  158. package/ts_interfaces/data/index.ts +18 -0
  159. package/ts_interfaces/data/remoteingress.ts +204 -0
  160. package/ts_interfaces/data/route-management.ts +436 -0
  161. package/ts_interfaces/data/security-policy.ts +37 -0
  162. package/ts_interfaces/data/smtp-account.ts +63 -0
  163. package/ts_interfaces/data/stats.ts +305 -0
  164. package/ts_interfaces/data/target-profile.ts +31 -0
  165. package/ts_interfaces/data/testing.ts +184 -0
  166. package/ts_interfaces/data/vpn.ts +68 -0
  167. package/ts_interfaces/data/workhoster.ts +72 -0
  168. package/ts_interfaces/index.ts +9 -0
  169. package/ts_interfaces/plugins.ts +6 -0
  170. package/ts_interfaces/readme.md +194 -0
  171. package/ts_interfaces/requests/acme-config.ts +54 -0
  172. package/ts_interfaces/requests/admin.ts +96 -0
  173. package/ts_interfaces/requests/api-tokens.ts +109 -0
  174. package/ts_interfaces/requests/certificate.ts +106 -0
  175. package/ts_interfaces/requests/combined.stats.ts +30 -0
  176. package/ts_interfaces/requests/config-events.ts +45 -0
  177. package/ts_interfaces/requests/config.ts +94 -0
  178. package/ts_interfaces/requests/dns-authority.ts +104 -0
  179. package/ts_interfaces/requests/dns-providers.ts +154 -0
  180. package/ts_interfaces/requests/dns-records.ts +113 -0
  181. package/ts_interfaces/requests/domains.ts +178 -0
  182. package/ts_interfaces/requests/email-domains.ts +193 -0
  183. package/ts_interfaces/requests/email-ops.ts +266 -0
  184. package/ts_interfaces/requests/email-settings.ts +34 -0
  185. package/ts_interfaces/requests/index.ts +29 -0
  186. package/ts_interfaces/requests/logs.ts +58 -0
  187. package/ts_interfaces/requests/network-targets.ts +127 -0
  188. package/ts_interfaces/requests/radius.ts +341 -0
  189. package/ts_interfaces/requests/realtime.ts +59 -0
  190. package/ts_interfaces/requests/remoteingress.ts +202 -0
  191. package/ts_interfaces/requests/route-management.ts +194 -0
  192. package/ts_interfaces/requests/security-policy.ts +144 -0
  193. package/ts_interfaces/requests/smtp-accounts.ts +163 -0
  194. package/ts_interfaces/requests/source-profiles.ts +127 -0
  195. package/ts_interfaces/requests/stats.ts +207 -0
  196. package/ts_interfaces/requests/target-profiles.ts +130 -0
  197. package/ts_interfaces/requests/testing.ts +186 -0
  198. package/ts_interfaces/requests/users.ts +66 -0
  199. package/ts_interfaces/requests/vpn.ts +238 -0
  200. package/ts_interfaces/requests/workhoster.ts +100 -0
@@ -0,0 +1,194 @@
1
+ # dcrouter interfaces
2
+
3
+ This folder contains the shared TypeScript data models and TypedRequest contracts used by dcrouter's OpsServer, dashboard, API client, tests, and external automation. It is published as the `./interfaces` subpath of `@serve.zone/dcrouter-apiclient`.
4
+
5
+ ## Issue Reporting and Security
6
+
7
+ For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pnpm add @serve.zone/dcrouter-apiclient
13
+ ```
14
+
15
+ ```typescript
16
+ import { data, requests } from '@serve.zone/dcrouter-apiclient/interfaces';
17
+ ```
18
+
19
+ That package installs on Linux x64 and arm64 only; see [Platform support](../ts_apiclient/readme.md#platform-support) for why and for the upstream fix that lifts it.
20
+
21
+ The same contracts remain exposed through the server package subpath, for consumers that already depend on it:
22
+
23
+ ```typescript
24
+ import { data, requests } from '@serve.zone/dcrouter/interfaces';
25
+ ```
26
+
27
+ ## What It Exports
28
+
29
+ | Export | Purpose |
30
+ | --- | --- |
31
+ | `data` | Shared runtime-shaped models such as identities, routes, route source bindings, DNS records, domains, email domains, remote ingress edges, VPN objects, stats, and security policy data. |
32
+ | `requests` | TypedRequest request/response contracts for OpsServer methods. |
33
+ | `typedrequestInterfaces` | Helper types re-exported from `@api.global/typedrequest-interfaces` through `plugins.ts`. |
34
+
35
+ ## Covered API Areas
36
+
37
+ | Area | Examples |
38
+ | --- | --- |
39
+ | Auth | admin login, first-admin bootstrap status/creation, logout, identity verification, users |
40
+ | Routes | merged route listing, operator route CRUD, managed HTTP-01 Special Forwards, toggles, warnings, ownership metadata, ordered source/path bindings |
41
+ | Access | API tokens, source profiles, target profiles, network targets |
42
+ | DNS and domains | DNS providers, domains, DNS records, ACME config |
43
+ | Email | email-domain management, email operations, and `TEmailOutboundMode` / `IEmailServerSettings.outboundMode` |
44
+ | Edge services | remote ingress, VPN, RADIUS, `IRemoteIngressEgressPolicyConfig`, and RemoteIngress status capabilities |
45
+ | Observability | stats, combined stats, logs, configuration |
46
+ | Gateway clients | dcrouter-local gateway client identity, token policy, and ownership metadata |
47
+
48
+ Canonical machine-facing gateway route, DNS, and domain contracts live in `@serve.zone/interfaces` under `data/gateway.ts` and `requests.gateway`. This package exposes dcrouter-local admin, token, route metadata, and OpsServer request shapes.
49
+
50
+ ### Email operation contracts
51
+
52
+ `getAllEmails` accepts an optional literal `search` string across sender,
53
+ recipients, subject, and message ID. Its response contains both the matching
54
+ `emails` and an `IEmailLogTraffic` series. Traffic defaults to the last 24 hours
55
+ and expands to 7, 14, or 30 days when an older retained search match requires it.
56
+
57
+ `getEmailSecurityFindings` returns retained inbound SPF, DKIM, and enforcing
58
+ DMARC failures as `IEmailSecurityFinding` records. Both methods require an
59
+ authenticated identity or API token with the `emails:read` scope.
60
+
61
+ Managed email domains expose durable reconciliation state through
62
+ `IEmailDomain.reconciliation`. During deletion,
63
+ `deletingProviderRecordIds` retains the provider IDs owned by the lifecycle
64
+ until an explicit provider not-found response or a complete provider-ID listing
65
+ proves that each record is absent.
66
+
67
+ RemoteIngress contracts include optional per-edge SMTP egress policy through `IRemoteIngressEgressPolicyConfig`. Edge status responses can include `capabilities` and `egressEnabled` so automation can distinguish connected egress-capable edges from ingress-only edges.
68
+
69
+ ## Route Source Binding Contracts
70
+
71
+ `data/route-management.ts` exports the source-binding contracts used by the dashboard, API client, and route runtime compiler:
72
+
73
+ - `IRouteMetadata.sourceBindings` stores ordered route-level source bindings.
74
+ - `IRouteSecurity` extends SmartProxy security with source-policy tri-state protection: omitted `rateLimit` or `challenge` means inherit, `null` means explicitly clear an inherited control, and an object means custom protection.
75
+ - `IRouteSourceBinding` points to a source profile, can override rate limits, browser challenges, or connection limits, and can contain path policies.
76
+ - `IRoutePathPolicyBinding` applies path-class-specific overrides within a source binding.
77
+ - `TRouteRateLimitExceededPolicy` derives SmartProxy rate-limit exceeded behavior from `IRouteConfig`: normal `429` or browser challenge through `rateLimit.onExceeded`.
78
+ - `IRouteSourcePolicyExceededAction` describes source-policy messages for effective rate-limit `429` responses only; it does not apply to connection-limit `429`s or other terminal denials. Browser challenge-on-exceeded behavior lives on `rateLimit.onExceeded`, not on this binding-level field.
79
+ - `IRouteSourcePolicy` and `IRouteSourcePolicyBinding` remain deprecated type aliases for old integrations; active route metadata uses `sourceBindings[]`.
80
+ - `TRoutePathClass` is the string-union type derived from `routePathClasses`.
81
+ - `routePathClasses` lists the supported classes: `git-smart-http`, `static`, `normal-html`, `expensive-html`, `raw`, and `archive`.
82
+ - `giteaRoutePathClassLabels` and `giteaRoutePathClassPatterns` provide the built-in Gitea labels and path patterns, including Git Smart HTTP and Git LFS patterns.
83
+
84
+ Effective source-policy protection resolves from the most specific scope outward: path policy, route binding, source profile, parent source profile, then no protection. Source profiles are reusable defaults only and do not enforce anything until referenced by a route binding.
85
+
86
+ ```typescript
87
+ import { data } from '@serve.zone/dcrouter-apiclient/interfaces';
88
+
89
+ const publicBinding: data.IRouteSourceBinding = {
90
+ sourceProfileRef: 'public-profile-id',
91
+ rateLimit: {
92
+ enabled: true,
93
+ maxRequests: 120,
94
+ window: 60,
95
+ keyBy: 'ip',
96
+ onExceeded: {
97
+ type: 'challenge',
98
+ challenge: {
99
+ providerId: 'smartchallenge',
100
+ challengeType: 'wait',
101
+ clearance: { ttlSeconds: 300, bindToHost: true },
102
+ },
103
+ clearanceEffect: 'bypass-rate-limit',
104
+ },
105
+ },
106
+ };
107
+
108
+ const trustedBinding: data.IRouteSourceBinding = {
109
+ sourceProfileRef: 'trusted-profile-id',
110
+ rateLimit: null,
111
+ };
112
+ ```
113
+
114
+ ## Managed Special Forward Contracts
115
+
116
+ `data/route-management.ts` exports `TManagedRouteKind` and `ILetsEncryptHttp01ForwardConfig`. The currently supported managed kind is `letsencrypt-http01-forward`. Callers provide a name, exact domains, either an inline target or `networkTargetRef`, and optional RemoteIngress settings; dcrouter owns the public port, challenge path, protocol, priority, and PUBLIC source binding.
117
+
118
+ The specialized route lifecycle uses these TypedRequest methods:
119
+
120
+ - `createLetsEncryptHttp01Forward`
121
+ - `updateLetsEncryptHttp01Forward`
122
+ - `deleteLetsEncryptHttp01Forward`
123
+
124
+ Managed routes remain visible through `getMergedRoutes` and can be toggled, but generic structural update and delete requests reject them. This prevents ordinary route editors from breaking the canonical HTTP-01 match or ownership metadata.
125
+
126
+ ## Raw TypedRequest Example
127
+
128
+ ```typescript
129
+ import { TypedRequest } from '@api.global/typedrequest';
130
+ import { data, requests } from '@serve.zone/dcrouter-apiclient/interfaces';
131
+
132
+ const identity: data.IIdentity = {
133
+ jwt: 'jwt-token',
134
+ userId: 'admin-1',
135
+ name: 'Admin',
136
+ expiresAt: Date.now() + 60_000,
137
+ role: 'admin',
138
+ type: 'user',
139
+ };
140
+
141
+ const request = new TypedRequest<requests.IReq_GetMergedRoutes>(
142
+ 'https://dcrouter.example.com/typedrequest',
143
+ 'getMergedRoutes',
144
+ );
145
+
146
+ const response = await request.fire({ identity });
147
+
148
+ for (const route of response.routes) {
149
+ console.log(route.id, route.origin, route.enabled, route.systemKey);
150
+ }
151
+ ```
152
+
153
+ ## Bootstrap Contracts
154
+
155
+ The auth request group includes `getAdminBootstrapStatus` and `createInitialAdminUser`. These exist so a fresh DB-backed dcrouter can require explicit first-admin creation instead of auto-persisting a default account. `createInitialAdminUser` requires the temporary bootstrap identity and can optionally enable `idp.global` authentication for the same normalized local email. The SDK defaults to hosted `https://idp.global`; dcrouter URL settings are overrides only.
156
+
157
+ ## When To Use It
158
+
159
+ - Use it in custom CLIs that call dcrouter's TypedRequest API directly.
160
+ - Use it in tests that need request/response types without the OO client.
161
+ - Use it in integrations where server and client code need the same data shapes.
162
+ - Use the `@serve.zone/dcrouter-apiclient` root export instead when you want higher-level managers and builders.
163
+
164
+ ## Development
165
+
166
+ This folder is built before `ts_apiclient` (`tspublish.json` order `1`) and is owned by that folder's package descriptor, which publishes it as the `./interfaces` subpath.
167
+
168
+ Useful source entry points:
169
+
170
+ - `index.ts` exports `data` and `requests` namespaces.
171
+ - `data/index.ts` groups shared data models.
172
+ - `requests/index.ts` groups TypedRequest contracts.
173
+ - `data/route-management.ts` defines route ownership, source/path policies, API token scopes, profiles, and network target shapes.
174
+
175
+ ## License and Legal Information
176
+
177
+ This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.
178
+
179
+ **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
180
+
181
+ ### Trademarks
182
+
183
+ This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
184
+
185
+ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
186
+
187
+ ### Company Information
188
+
189
+ Task Venture Capital GmbH
190
+ Registered at District Court Bremen HRB 35230 HB, Germany
191
+
192
+ For any legal inquiries or further information, please contact us via email at hello@task.vc.
193
+
194
+ By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
@@ -0,0 +1,54 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IAcmeConfig } from '../data/acme-config.js';
4
+
5
+ // ============================================================================
6
+ // ACME Config Endpoints
7
+ // ============================================================================
8
+
9
+ /**
10
+ * Get the current ACME configuration. Returns null if no config has been
11
+ * set yet (neither from DB nor seeded from the constructor).
12
+ */
13
+ export interface IReq_GetAcmeConfig extends plugins.typedrequestInterfaces.implementsTR<
14
+ plugins.typedrequestInterfaces.ITypedRequest,
15
+ IReq_GetAcmeConfig
16
+ > {
17
+ method: 'getAcmeConfig';
18
+ request: {
19
+ identity?: authInterfaces.IIdentity;
20
+ apiToken?: string;
21
+ };
22
+ response: {
23
+ config: IAcmeConfig | null;
24
+ };
25
+ }
26
+
27
+ /**
28
+ * Update the ACME configuration (upsert). All fields are required on first
29
+ * create, optional on subsequent updates (partial update).
30
+ *
31
+ * NOTE: Most fields take effect on the next dcrouter restart — SmartAcme is
32
+ * instantiated once at startup. `renewThresholdDays` applies immediately to
33
+ * the next renewal check.
34
+ */
35
+ export interface IReq_UpdateAcmeConfig extends plugins.typedrequestInterfaces.implementsTR<
36
+ plugins.typedrequestInterfaces.ITypedRequest,
37
+ IReq_UpdateAcmeConfig
38
+ > {
39
+ method: 'updateAcmeConfig';
40
+ request: {
41
+ identity?: authInterfaces.IIdentity;
42
+ apiToken?: string;
43
+ accountEmail?: string;
44
+ enabled?: boolean;
45
+ useProduction?: boolean;
46
+ autoRenew?: boolean;
47
+ renewThresholdDays?: number;
48
+ };
49
+ response: {
50
+ success: boolean;
51
+ config?: IAcmeConfig;
52
+ message?: string;
53
+ };
54
+ }
@@ -0,0 +1,96 @@
1
+ import * as plugins from '../plugins.js';
2
+ import * as authInterfaces from '../data/auth.js';
3
+
4
+ export type TAdminLoginAuthSource = 'auto' | 'local' | 'idp.global';
5
+
6
+ export interface IAdminUserProjection {
7
+ id: string;
8
+ username: string;
9
+ email?: string;
10
+ name?: string;
11
+ role: string;
12
+ status?: 'active' | 'disabled';
13
+ authSources?: Array<'local' | 'idp.global'>;
14
+ }
15
+
16
+ // Admin Login
17
+ export interface IReq_AdminLoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR<
18
+ plugins.typedrequestInterfaces.ITypedRequest,
19
+ IReq_AdminLoginWithUsernameAndPassword
20
+ > {
21
+ method: 'adminLoginWithUsernameAndPassword';
22
+ request: {
23
+ username: string;
24
+ password: string;
25
+ authSource?: TAdminLoginAuthSource;
26
+ };
27
+ response: {
28
+ identity?: authInterfaces.IIdentity;
29
+ };
30
+ }
31
+
32
+ // Admin bootstrap status
33
+ export interface IReq_GetAdminBootstrapStatus extends plugins.typedrequestInterfaces.implementsTR<
34
+ plugins.typedrequestInterfaces.ITypedRequest,
35
+ IReq_GetAdminBootstrapStatus
36
+ > {
37
+ method: 'getAdminBootstrapStatus';
38
+ request: {};
39
+ response: {
40
+ dbEnabled: boolean;
41
+ dbReady: boolean;
42
+ hasPersistentAdmin: boolean;
43
+ needsBootstrap: boolean;
44
+ ephemeralAdminAvailable: boolean;
45
+ idpGlobalConfigured: boolean;
46
+ };
47
+ }
48
+
49
+ // Create the first persisted admin account. Requires the bootstrap/ephemeral admin identity.
50
+ export interface IReq_CreateInitialAdminUser extends plugins.typedrequestInterfaces.implementsTR<
51
+ plugins.typedrequestInterfaces.ITypedRequest,
52
+ IReq_CreateInitialAdminUser
53
+ > {
54
+ method: 'createInitialAdminUser';
55
+ request: {
56
+ identity: authInterfaces.IIdentity;
57
+ email: string;
58
+ name?: string;
59
+ password: string;
60
+ enableIdpGlobalAuth?: boolean;
61
+ };
62
+ response: {
63
+ success: boolean;
64
+ identity?: authInterfaces.IIdentity;
65
+ user?: IAdminUserProjection;
66
+ };
67
+ }
68
+
69
+ // Admin Logout
70
+ export interface IReq_AdminLogout extends plugins.typedrequestInterfaces.implementsTR<
71
+ plugins.typedrequestInterfaces.ITypedRequest,
72
+ IReq_AdminLogout
73
+ > {
74
+ method: 'adminLogout';
75
+ request: {
76
+ identity: authInterfaces.IIdentity;
77
+ };
78
+ response: {
79
+ success: boolean;
80
+ };
81
+ }
82
+
83
+ // Verify Identity
84
+ export interface IReq_VerifyIdentity extends plugins.typedrequestInterfaces.implementsTR<
85
+ plugins.typedrequestInterfaces.ITypedRequest,
86
+ IReq_VerifyIdentity
87
+ > {
88
+ method: 'verifyIdentity';
89
+ request: {
90
+ identity: authInterfaces.IIdentity;
91
+ };
92
+ response: {
93
+ valid: boolean;
94
+ identity?: authInterfaces.IIdentity;
95
+ };
96
+ }
@@ -0,0 +1,109 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IApiTokenInfo, IApiTokenPolicy, TApiTokenScope } from '../data/route-management.js';
4
+
5
+ // ============================================================================
6
+ // API Token Management Endpoints
7
+ // ============================================================================
8
+
9
+ /**
10
+ * Create a new API token. Returns the raw token value once (never shown again).
11
+ * Admin JWT only — tokens cannot create tokens.
12
+ */
13
+ export interface IReq_CreateApiToken extends plugins.typedrequestInterfaces.implementsTR<
14
+ plugins.typedrequestInterfaces.ITypedRequest,
15
+ IReq_CreateApiToken
16
+ > {
17
+ method: 'createApiToken';
18
+ request: {
19
+ identity?: authInterfaces.IIdentity;
20
+ apiToken?: string;
21
+ name: string;
22
+ scopes: TApiTokenScope[];
23
+ policy?: IApiTokenPolicy;
24
+ expiresInDays?: number | null;
25
+ };
26
+ response: {
27
+ success: boolean;
28
+ tokenId?: string;
29
+ tokenValue?: string;
30
+ message?: string;
31
+ };
32
+ }
33
+
34
+ /**
35
+ * List all API tokens (without hashes).
36
+ */
37
+ export interface IReq_ListApiTokens extends plugins.typedrequestInterfaces.implementsTR<
38
+ plugins.typedrequestInterfaces.ITypedRequest,
39
+ IReq_ListApiTokens
40
+ > {
41
+ method: 'listApiTokens';
42
+ request: {
43
+ identity?: authInterfaces.IIdentity;
44
+ apiToken?: string;
45
+ };
46
+ response: {
47
+ tokens: IApiTokenInfo[];
48
+ };
49
+ }
50
+
51
+ /**
52
+ * Revoke (delete) an API token.
53
+ */
54
+ export interface IReq_RevokeApiToken extends plugins.typedrequestInterfaces.implementsTR<
55
+ plugins.typedrequestInterfaces.ITypedRequest,
56
+ IReq_RevokeApiToken
57
+ > {
58
+ method: 'revokeApiToken';
59
+ request: {
60
+ identity?: authInterfaces.IIdentity;
61
+ apiToken?: string;
62
+ id: string;
63
+ };
64
+ response: {
65
+ success: boolean;
66
+ message?: string;
67
+ };
68
+ }
69
+
70
+ /**
71
+ * Roll (regenerate) an API token's secret. Returns the new raw token value once.
72
+ * Admin JWT only.
73
+ */
74
+ export interface IReq_RollApiToken extends plugins.typedrequestInterfaces.implementsTR<
75
+ plugins.typedrequestInterfaces.ITypedRequest,
76
+ IReq_RollApiToken
77
+ > {
78
+ method: 'rollApiToken';
79
+ request: {
80
+ identity?: authInterfaces.IIdentity;
81
+ apiToken?: string;
82
+ id: string;
83
+ };
84
+ response: {
85
+ success: boolean;
86
+ tokenValue?: string;
87
+ message?: string;
88
+ };
89
+ }
90
+
91
+ /**
92
+ * Enable or disable an API token.
93
+ */
94
+ export interface IReq_ToggleApiToken extends plugins.typedrequestInterfaces.implementsTR<
95
+ plugins.typedrequestInterfaces.ITypedRequest,
96
+ IReq_ToggleApiToken
97
+ > {
98
+ method: 'toggleApiToken';
99
+ request: {
100
+ identity?: authInterfaces.IIdentity;
101
+ apiToken?: string;
102
+ id: string;
103
+ enabled: boolean;
104
+ };
105
+ response: {
106
+ success: boolean;
107
+ message?: string;
108
+ };
109
+ }
@@ -0,0 +1,106 @@
1
+ import * as plugins from '../plugins.js';
2
+ import * as authInterfaces from '../data/auth.js';
3
+
4
+ export type TCertificateStatus = 'valid' | 'expiring' | 'expired' | 'provisioning' | 'failed' | 'unknown';
5
+ export type TCertificateSource = 'acme' | 'provision-function' | 'static' | 'none';
6
+
7
+ /**
8
+ * What the running proxy is actually presenting on the wire for a domain, as
9
+ * reported by the Rust engine.
10
+ *
11
+ * This is deliberately separate from the issued/stored view: a certificate can be
12
+ * valid in storage while the engine still serves an older, expired one, and
13
+ * reporting only the stored view is how a 21-day outage went unnoticed. Absent
14
+ * when the engine cannot be queried — absence means "unknown", never "fine".
15
+ */
16
+ export interface ICertificateServedState {
17
+ expiryDate?: string; // ISO string
18
+ isValid: boolean;
19
+ source?: string;
20
+ }
21
+
22
+ export interface ICertificateInfo {
23
+ domain: string;
24
+ routeNames: string[];
25
+ /** Combined verdict. Downgraded to 'failed' whenever `servedMismatch` is true. */
26
+ status: TCertificateStatus;
27
+ source: TCertificateSource;
28
+ tlsMode: 'terminate' | 'terminate-and-reencrypt' | 'passthrough';
29
+ /** Expiry of the issued/stored certificate. */
30
+ expiryDate?: string; // ISO string
31
+ issuer?: string;
32
+ issuedAt?: string; // ISO string
33
+ error?: string; // if status === 'failed'
34
+ canReprovision: boolean; // true for acme/provision-function routes
35
+ /** What the running proxy serves, when determinable. */
36
+ served?: ICertificateServedState;
37
+ /**
38
+ * True when a valid certificate is issued/stored but the proxy is still serving
39
+ * an invalid or expired one. An issuance success must never mask this.
40
+ */
41
+ servedMismatch?: boolean;
42
+ backoffInfo?: {
43
+ failures: number;
44
+ retryAfter?: string; // ISO string
45
+ lastError?: string;
46
+ };
47
+ }
48
+
49
+ export interface IReq_GetCertificateOverview extends plugins.typedrequestInterfaces.implementsTR<
50
+ plugins.typedrequestInterfaces.ITypedRequest,
51
+ IReq_GetCertificateOverview
52
+ > {
53
+ method: 'getCertificateOverview';
54
+ request: {
55
+ identity?: authInterfaces.IIdentity;
56
+ apiToken?: string;
57
+ };
58
+ response: {
59
+ certificates: ICertificateInfo[];
60
+ summary: {
61
+ total: number;
62
+ valid: number;
63
+ expiring: number;
64
+ expired: number;
65
+ failed: number;
66
+ unknown: number;
67
+ };
68
+ };
69
+ }
70
+
71
+ export interface IReq_ReprovisionCertificateDomain extends plugins.typedrequestInterfaces.implementsTR<
72
+ plugins.typedrequestInterfaces.ITypedRequest,
73
+ IReq_ReprovisionCertificateDomain
74
+ > {
75
+ method: 'reprovisionCertificateDomain';
76
+ request: {
77
+ identity?: authInterfaces.IIdentity;
78
+ apiToken?: string;
79
+ domain: string;
80
+ forceRenew?: boolean;
81
+ };
82
+ response: {
83
+ success: boolean;
84
+ message?: string;
85
+ };
86
+ }
87
+
88
+ // Delete a certificate by domain
89
+ export interface IReq_DeleteCertificate extends plugins.typedrequestInterfaces.implementsTR<
90
+ plugins.typedrequestInterfaces.ITypedRequest,
91
+ IReq_DeleteCertificate
92
+ > {
93
+ method: 'deleteCertificate';
94
+ request: {
95
+ identity?: authInterfaces.IIdentity;
96
+ apiToken?: string;
97
+ domain: string;
98
+ };
99
+ response: {
100
+ success: boolean;
101
+ message?: string;
102
+ };
103
+ }
104
+
105
+ // The certificate import/export contracts live in @serve.zone/interfaces
106
+ // (requests/gateway.ts).
@@ -0,0 +1,30 @@
1
+ import type * as data from '../data/index.js';
2
+
3
+ export interface IReq_GetCombinedMetrics {
4
+ method: 'getCombinedMetrics';
5
+ request: {
6
+ identity?: data.IIdentity;
7
+ apiToken?: string;
8
+ sections?: {
9
+ server?: boolean;
10
+ email?: boolean;
11
+ dns?: boolean;
12
+ security?: boolean;
13
+ network?: boolean;
14
+ radius?: boolean;
15
+ vpn?: boolean;
16
+ };
17
+ };
18
+ response: {
19
+ metrics: {
20
+ server?: data.IServerStats;
21
+ email?: data.IEmailStats;
22
+ dns?: data.IDnsStats;
23
+ security?: data.ISecurityMetrics;
24
+ network?: data.INetworkMetrics;
25
+ radius?: data.IRadiusStats;
26
+ vpn?: data.IVpnStats;
27
+ };
28
+ timestamp: number;
29
+ };
30
+ }
@@ -0,0 +1,45 @@
1
+ import * as plugins from '../plugins.js';
2
+ import * as authInterfaces from '../data/auth.js';
3
+ import * as configEventInterfaces from '../data/config-events.js';
4
+
5
+ // List platform configuration events
6
+ export interface IReq_ListConfigEvents extends plugins.typedrequestInterfaces.implementsTR<
7
+ plugins.typedrequestInterfaces.ITypedRequest,
8
+ IReq_ListConfigEvents
9
+ > {
10
+ method: 'listConfigEvents';
11
+ request: {
12
+ identity?: authInterfaces.IIdentity;
13
+ apiToken?: string;
14
+ /** Filter by acknowledgement state; omit for all events. */
15
+ acknowledged?: boolean;
16
+ severity?: configEventInterfaces.TOpsConfigEventSeverity;
17
+ category?: string;
18
+ limit?: number;
19
+ cursor?: configEventInterfaces.IOpsConfigEventCursor;
20
+ };
21
+ response: {
22
+ events: configEventInterfaces.IOpsConfigEvent[];
23
+ total: number;
24
+ unacknowledgedCount: number;
25
+ nextCursor?: configEventInterfaces.IOpsConfigEventCursor;
26
+ };
27
+ }
28
+
29
+ // Acknowledge platform configuration events
30
+ export interface IReq_AcknowledgeConfigEvents extends plugins.typedrequestInterfaces.implementsTR<
31
+ plugins.typedrequestInterfaces.ITypedRequest,
32
+ IReq_AcknowledgeConfigEvents
33
+ > {
34
+ method: 'acknowledgeConfigEvents';
35
+ request: {
36
+ identity?: authInterfaces.IIdentity;
37
+ apiToken?: string;
38
+ ids: string[];
39
+ };
40
+ response: {
41
+ success: boolean;
42
+ acknowledgedCount: number;
43
+ message?: string;
44
+ };
45
+ }