UPDATE

2026-05-10 02:29:38 +03:00
parent efcf3c7905
commit 37b9a13d52
8 changed files with 1158 additions and 140 deletions
@@ -0,0 +1,314 @@
+# Core Routes
+
+This file lists the current HTTP routes exposed by Core, grouped by access level.
+
+## Common conventions
+
+- Authenticated routes use JWT unless noted otherwise.
+- Admin routes require `role = admin`.
+- Node-private routes require the `x-node-auth-key` header and are documented separately in [`core-private-routes.md`](./core-private-routes.md).
+- The API returns raw JSON objects and arrays, not a wrapper object.
+
+## Public routes
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/health` | none | `{ status: 'ok', timestamp }` |
+| `GET` | `/metrics` | none | Prometheus text format |
+| `POST` | `/auth/register` | `RegisterDto` | Creates a user account |
+| `POST` | `/auth/login` | `LoginDto` | Returns JWT tokens |
+| `POST` | `/auth/refresh` | `RefreshTokenDto` | Returns new JWT tokens |
+| `POST` | `/auth/telegram` | `TelegramAuthDto` | Telegram OAuth login |
+| `GET` | `/auth/telegram/bot-id` | none | `{ botId }` |
+| `GET` | `/sub/:uuid/info` | query string and request IP | Returns `SubscriptionInfo` JSON |
+| `GET` | `/sub/:uuid` | `format=v2ray|clash|singbox` | Returns encoded subscription content |
+
+### `/sub/:uuid` output
+
+- `format=v2ray` - plain text, newline-separated URIs
+- `format=clash` - YAML with `proxies`
+- `format=singbox` - JSON with `outbounds`
+- unknown or missing `format` falls back to `v2ray`
+
+## Authenticated user routes
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/auth/me` | none | Current user without `passwordHash` |
+| `POST` | `/auth/telegram/link` | `TelegramAuthDto` | Links Telegram to the current account |
+| `DELETE` | `/auth/telegram/unlink` | none | Unlinks Telegram from the current account |
+| `GET` | `/me` | none | Current user without `passwordHash` |
+| `PATCH` | `/me/profile` | `UpdateProfileDto` | Updates name, email, or password |
+| `GET` | `/me/stats` | none | `UserStats` |
+| `GET` | `/me/traffic/daily` | none | Daily traffic series |
+| `GET` | `/me/traffic/hourly-dist` | none | Hour-of-day distribution |
+| `GET` | `/me/traffic` | `period=30d|7d|1d|1h` | Period traffic series |
+| `GET` | `/me/balance` | none | `{ balance }` |
+| `GET` | `/me/balance/transactions` | none | User balance transaction history |
+| `GET` | `/me/subscriptions` | none | User subscriptions |
+| `GET` | `/me/links` | none | All user subscription links |
+| `GET` | `/me/configs` | none | Available node/protocol configs for the current user |
+| `POST` | `/me/links` | `CreateUserLinkDto` | Creates a combined link or a per-subscription link |
+| `POST` | `/me/subscriptions` | `CreateSubscriptionLinkDto` | Legacy per-subscription link creation |
+| `POST` | `/me/subscriptions/:id/reset` | none | Resets the selected link UUID |
+| `PATCH` | `/me/subscriptions/links/:id` | `UpdateSubscriptionLinkDto` | Renames or reconfigures a link |
+| `DELETE` | `/me/subscriptions/links/:id` | none | Deletes a link |
+| `PATCH` | `/me/subscriptions/:id/auto-renew` | `UpdateAutoRenewDto` | Toggles auto-renew for own subscription |
+
+## Admin routes - users
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/users` | `page`, `limit`, `search`, `status`, `isBlocked` | Paginated users |
+| `GET` | `/admin/users/:id` | none | User detail |
+| `GET` | `/admin/users/:id/stats` | none | User stats |
+| `PATCH` | `/admin/users/:id` | `UpdateUserDto` | Updates email, password, role, block flag, name, comment |
+| `PATCH` | `/admin/users/:id/status` | `UpdateUserStatusDto` | Approves, rejects, or restores a user |
+| `DELETE` | `/admin/users/:id` | none | Deletes a user |
+
+## Admin routes - balance
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `POST` | `/admin/users/:id/balance/transactions` | `CreateBalanceTransactionDto` | Creates a deposit, withdrawal, or refund |
+| `GET` | `/admin/users/:id/balance` | none | `{ balance }` |
+| `GET` | `/admin/users/:id/balance/transactions` | none | Full admin transaction history |
+| `PATCH` | `/admin/balance/transactions/:id` | `UpdateBalanceTransactionDto` | Edits a balance transaction |
+
+## Admin routes - tariffs
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/tariffs` | none | Tariff list |
+| `GET` | `/admin/tariffs/:id` | none | Tariff detail |
+| `POST` | `/admin/tariffs` | `CreateTariffDto` | Creates a tariff |
+| `PATCH` | `/admin/tariffs/:id` | `UpdateTariffDto` | Updates a tariff |
+| `DELETE` | `/admin/tariffs/:id` | none | Deletes a tariff |
+
+## Admin routes - subscriptions
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/subscriptions` | `page`, `limit`, `status`, `userId`, `tariffId` | Paginated subscriptions |
+| `GET` | `/admin/users/:id/subscriptions` | none | Subscriptions for a user |
+| `GET` | `/admin/users/:id/links` | none | All links for a user |
+| `POST` | `/admin/subscriptions` | `CreateSubscriptionDto` | Creates a subscription |
+| `DELETE` | `/admin/subscriptions/:id` | none | Cancels a subscription |
+| `PATCH` | `/admin/subscriptions/:id/auto-renew` | `UpdateAutoRenewDto` | Toggles auto-renew |
+| `POST` | `/admin/users/:id/links` | `CreateUserLinkDto` | Creates a link for any user |
+| `POST` | `/admin/subscriptions/:id/links` | `CreateSubscriptionLinkDto` | Creates a link for a specific subscription |
+| `POST` | `/admin/subscriptions/links/:id/reset` | none | Resets a link UUID |
+| `PATCH` | `/admin/subscriptions/links/:id` | `UpdateSubscriptionLinkDto` | Updates a link |
+| `DELETE` | `/admin/subscriptions/links/:id` | none | Deletes a link |
+
+## Admin routes - nodes
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/nodes` | `page`, `limit` | Paginated nodes |
+| `GET` | `/admin/nodes/status` | none | Computed node status list |
+| `GET` | `/admin/nodes/outbound-options` | none | Node/protocol outbound options |
+| `GET` | `/admin/nodes/:id` | none | Node detail |
+| `POST` | `/admin/nodes` | `CreateNodeDto` | Creates a node |
+| `PATCH` | `/admin/nodes/:id` | `UpdateNodeDto` | Updates a node |
+| `DELETE` | `/admin/nodes/:id` | none | Deletes a node |
+| `POST` | `/admin/nodes/:id/sync` | none | Forces a config sync |
+| `POST` | `/admin/nodes/auth-code` | none | Generates a one-time node registration code |
+| `POST` | `/admin/nodes/:id/rotate-key` | none | Rotates the node auth key |
+| `GET` | `/admin/nodes/:id/protocols` | none | Node protocols |
+| `POST` | `/admin/nodes/:id/protocols` | `CreateProtocolDto` | Creates a node protocol |
+| `PUT` | `/admin/nodes/:id/protocols/:protocolId` | `UpdateProtocolDto` | Updates a node protocol |
+| `DELETE` | `/admin/nodes/:id/protocols/:protocolId` | none | Deletes a node protocol |
+| `GET` | `/admin/nodes/:id/accesses` | none | User access map for the node |
+| `POST` | `/admin/nodes/:nodeId/access/:userId/:protocol` | none | Grants protocol access |
+| `DELETE` | `/admin/nodes/:nodeId/access/:userId/:protocol` | none | Revokes protocol access |
+| `POST` | `/admin/nodes/:id/install-xray` | `InstallXrayDto` | Installs an xray version and stores the result |
+| `POST` | `/admin/nodes/:id/restart-xray` | none | Restarts xray |
+| `POST` | `/admin/nodes/:id/update-geoip` | `UpdateGeoipDto` | Updates stored geoip/geosite URLs and node files |
+| `POST` | `/admin/nodes/:id/crypto/x25519` | none | Generates x25519 keys |
+| `POST` | `/admin/nodes/:id/crypto/mldsa65` | none | Generates ML-DSA-65 keys |
+| `GET` | `/admin/nodes/xray/versions` | none | Cached xray release tags |
+| `GET` | `/admin/nodes/mtproto/versions` | none | Cached telemt release tags |
+| `PATCH` | `/admin/nodes/:id/routing-config` | `UpdateNodeRoutingConfigDto` | Updates per-node routing config |
+| `POST` | `/admin/nodes/:id/routing-config/apply-template` | `ApplyRoutingTemplateDto` | Copies a routing template into the node config |
+| `DELETE` | `/admin/nodes/:id/routing-config` | none | Clears per-node routing config |
+| `PUT` | `/admin/nodes/:id/nginx/site` | multipart form-data | Uploads cert/key/html for a masking site |
+| `GET` | `/admin/nodes/:id/nginx/site` | none | Returns nginx masking site status |
+| `DELETE` | `/admin/nodes/:id/nginx/sites/:domain` | none | Deletes a masking site |
+| `POST` | `/admin/nodes/:id/install-mtproto` | body `{ version?: string }` | Installs telemt and stores the version |
+| `POST` | `/admin/nodes/:id/restart-mtproto` | none | Restarts telemt |
+| `GET` | `/admin/nodes/:id/runtime-status` | none | Live runtime status from the node |
+| `GET` | `/admin/nodes/:id/outbounds` | none | Node outbounds |
+| `POST` | `/admin/nodes/:id/outbounds` | `CreateNodeOutboundDto` | Creates a node outbound |
+| `PATCH` | `/admin/nodes/:id/outbounds/:outboundId` | partial `CreateNodeOutboundDto` | Updates a node outbound |
+| `DELETE` | `/admin/nodes/:id/outbounds/:outboundId` | none | Deletes a node outbound |
+
+## Admin routes - routing rule sets
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/routing-rule-sets` | none | All routing rule sets |
+| `POST` | `/admin/routing-rule-sets` | `CreateRoutingRuleSetDto` | Creates a routing rule set |
+| `PATCH` | `/admin/routing-rule-sets/:id` | `CreateRoutingRuleSetDto` | Updates a routing rule set |
+| `DELETE` | `/admin/routing-rule-sets/:id` | none | Deletes a routing rule set |
+
+## Admin routes - external subscriptions
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/external-subscriptions` | none | External subscription sources |
+| `GET` | `/admin/external-subscriptions/:id` | none | External subscription source detail |
+| `POST` | `/admin/external-subscriptions` | `CreateExternalSubscriptionDto` | Creates a source |
+| `POST` | `/admin/external-subscriptions/test` | `TestExternalSubscriptionDto` | Tests a URL and returns source data |
+| `PATCH` | `/admin/external-subscriptions/:id` | `UpdateExternalSubscriptionDto` | Updates a source |
+| `DELETE` | `/admin/external-subscriptions/:id` | none | Deletes a source |
+
+## Admin routes - logs and usage
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `GET` | `/admin/logs` | `page`, `limit`, `action`, `userId` | Paginated audit logs |
+| `GET` | `/admin/usage` | `nodeId`, `userId`, `from`, `to` | Up to 1000 traffic usage rows |
+
+## Admin routes - xray helpers
+
+| Method | Route | Input | Output / Notes |
+| --- | --- | --- | --- |
+| `POST` | `/admin/xray/parse-link` | `{ link }` | Parses a proxy link into outbound config |
+
+## DTO summary
+
+### Auth
+
+- `LoginDto` - `email`, `password`
+- `RegisterDto` - `email`, `password`
+- `RefreshTokenDto` - `refreshToken`
+- `TelegramAuthDto` - `tgAuthResult`
+
+### Users
+
+- `UpdateProfileDto` - `name?`, `email?`, `password?`
+- `UpdateUserDto` - `email?`, `password?`, `role?`, `isBlocked?`, `name?`, `comment?`
+- `UpdateUserStatusDto` - `status: 'active' | 'pending' | 'rejected'`
+
+### Balance
+
+- `CreateBalanceTransactionDto` - `amount`, `type`, `comment?`, `createdAt?`
+- `UpdateBalanceTransactionDto` - `amount?`, `type?`, `comment?`
+
+### Tariffs
+
+- `CreateTariffDto`
+  - `name`
+  - `durationMonths: number | null`
+  - `price`
+  - `trafficLimitBytes?`
+  - `isActive?`
+  - `allowedProtocols: VpnProtocol[]`
+  - `allowedNodeIds?`
+  - `externalSubscriptionIds?`
+  - `allowBittorrent?`
+  - `allowAdult?`
+- `UpdateTariffDto` - partial `CreateTariffDto`
+
+### Subscriptions
+
+- `CreateSubscriptionDto` - `userId`, `tariffId`, `startAt?`
+- `CreateSubscriptionLinkDto` - `subscriptionId`, `name?`
+- `CreateUserLinkDto` - `subscriptionId?`, `name?`, `selectedNodeIds?`
+- `UpdateSubscriptionLinkDto` - `name?`, `isEnabled?`, `selectedNodeIds?`
+- `UpdateAutoRenewDto` - `autoRenew`
+
+### Nodes
+
+- `CreateNodeDto`
+  - `name`
+  - `host`
+  - `port?`
+  - `useSsl?`
+  - `ip?`
+  - `region?`
+  - `metadata?`
+  - `comment?`
+  - `emoji?`
+  - `status?`
+  - `useIpInSubscription?`
+- `UpdateNodeDto` - partial `CreateNodeDto` plus `geoipUrl?` and `geositeUrl?`
+- `CreateProtocolDto` - `protocol`, `config?`, `label?`, `isEnabled?`
+- `UpdateProtocolDto` - `config?`, `label?`, `isEnabled?`
+- `CreateNodeOutboundDto`
+  - `name`
+  - `tag`
+  - `outboundType?` = `manual | node`
+  - `config?`
+  - `targetNodeId?`
+  - `targetProtocolId?`
+- `CreateRoutingRuleSetDto`
+  - `name`
+  - `description?`
+  - `domainStrategy?`
+  - `rules?`
+  - `balancers?`
+  - `blockTorrents?`
+  - `blockAds?`
+  - `blockMalware?`
+  - `blockPhishing?`
+  - `blockCryptominers?`
+  - `blockAdult?`
+- `UpdateNodeRoutingConfigDto` - same routing fields as above, without `name` and `description`
+- `ApplyRoutingTemplateDto` - `templateId`
+- `InstallXrayDto` - `version`
+- `UpdateGeoipDto` - `geoipUrl?`, `geositeUrl?`
+
+### External subscriptions
+
+- `CreateExternalSubscriptionDto` - `name`, `url`, `description?`
+- `UpdateExternalSubscriptionDto` - partial `CreateExternalSubscriptionDto`
+- `TestExternalSubscriptionDto` - `url`
+
+### Routing rules
+
+`XrayRule` fields:
+
+- `type` (`field`)
+- `domainMatcher?`
+- `domain?`
+- `ip?`
+- `port?`
+- `sourcePort?`
+- `localPort?`
+- `network?`
+- `source?`
+- `sourceIP?`
+- `localIP?`
+- `user?`
+- `inboundTag?`
+- `protocol?`
+- `attrs?`
+- `process?`
+- `vlessRoute?`
+- `webhook?`
+- `outboundTag?`
+- `balancerTag?`
+- `ruleTag?`
+
+`XrayBalancer` fields:
+
+- `tag`
+- `selector`
+- `strategy?`
+- `fallbackTag?`
+
+`XrayDomainStrategy` values:
+
+- `AsIs`
+- `IPIfNonMatch`
+- `IPOnDemand`
+
+`XrayBalancerStrategy` values:
+
+- `random`
+- `roundRobin`
+- `leastPing`
+- `leastLoad`
+