From af951f4db3279e83e52c34bf9f1ee7f910ab39ca Mon Sep 17 00:00:00 2001 From: Alexey <247128645+axkurcom@users.noreply.github.com> Date: Fri, 6 Nov 2026 22:47:40 +0300 Subject: [PATCH] Update API.md --- docs/Architecture/API/API.md | 137 ++++++++++++++++++++++++++++++----- 1 file changed, 117 insertions(+), 20 deletions(-) diff --git a/docs/Architecture/API/API.md b/docs/Architecture/API/API.md index 9b9ebfa..62bc28b 100644 --- a/docs/Architecture/API/API.md +++ b/docs/Architecture/API/API.md @@ -38,10 +38,10 @@ applies `whitelist`, `gray_action`, `auth_header`, `request_body_limit_bytes`, `minimal_runtime_enabled`, `minimal_runtime_cache_ttl_ms`, `runtime_edge_enabled`, `runtime_edge_cache_ttl_ms`, `runtime_edge_top_n`, and `read_only`. `enabled`, `listen`, and `runtime_edge_events_capacity` remain -process-owned and require a process restart. These fields are configured in the -owning TOML source; `PATCH /v1/config` currently accepts only `server.listeners` -under `server`. A client polling after an authentication change must use the new -header explicitly. +process-owned and require a process restart. The five [observability settings](#api-observability-settings) +are editable through `PATCH /v1/config`; other API settings require editing the +owning TOML source. A client polling after an authentication change must use the +new header explicitly. ## Protocol Contract @@ -100,7 +100,7 @@ Notes: ## Python client and CLI -The standard-library [Python client](../../../tools/telemt_api.py) covers the 51 +The standard-library [Python client](../../../tools/telemt_api.py) covers the 53 JSON operations, including discovery, preflight/state, user quota/period/rates, generation reload and WEB lifecycle/session controls. The HTML `/web-status` viewer remains a browser endpoint. See the [client guide](PYTHON_CLIENT.md) for @@ -155,6 +155,8 @@ operations or pending publication; they are not silently promoted to success. | `GET` | `/v1/stats/users/active-ips` | none | `200` | `UserActiveIps[]` | | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` | | `GET` | `/v1/stats/users/quota` | none | `200` | User quota counters and recurring schedule status in `data.users`. | +| `GET` | `/v1/access/policy` | none | `200` | Desired/effective access policy | +| `PATCH` | `/v1/access/policy` | `AccessPolicyPatch` | `200` | Desired/effective access policy with changed paths | | `GET` | `/v1/config` | none | `200` | `ConfigData` | | `PATCH` | `/v1/config` | sparse JSON object; optional reload query | `200` or `202` | `PatchConfigResponse` | | `POST` | `/v1/config/validate` | same sparse patch, preconditions and reload query | `200` | `ConfigValidationData` | @@ -210,6 +212,8 @@ operations or pending publication; they are not silently promoted to success. | `POST /v1/runtime/web/lifecycle/resume` | Cancels an active drain, if any, and reopens only the operator-owned admission fence. | | `GET /v1/stats/users/active-ips` | Returns users that currently have non-empty active source-IP lists. | | `GET /v1/stats/users` | Alias of `GET /v1/users`; returns disk-first user views with runtime lag flag. | +| `GET /v1/access/policy` | Desired and published shared access limits and CIDR rate rules, with source revision and runtime token. | +| `PATCH /v1/access/policy` | Atomic policy edit; optional `If-Match` and `If-Runtime-Match`. Watcher publication is asynchronous. | | `GET /v1/config` | Returns the current editable config sections as JSON (no `access.*`) plus the revision. | | `PATCH /v1/config` | Applies a sparse patch and optionally submits an in-process runtime reload to Maestro. | | `POST /v1/config/validate` | Prepares and classifies a candidate without persistence or runtime publication; allowed in read-only mode. | @@ -232,7 +236,7 @@ operations or pending publication; they are not silently promoted to success. | `400` | `bad_request` | Invalid JSON, validation failures, malformed request body. | | `400` | `access_not_editable` | `PATCH /v1/config` body contains an `access` key (managed via users API). | | `400` | `section_not_editable` | `PATCH /v1/config` body contains an unknown top-level key or a non-null, non-object partial section. | -| `400` | `field_not_editable` | `PATCH /v1/config` body contains a forbidden nested field under a partially editable section (e.g. `server.api`, `server.port`, `network.ipv4`). | +| `400` | `field_not_editable` | `PATCH /v1/config` body contains a forbidden nested field under a partially editable section (e.g. `server.api.auth_header`, `server.port`, `network.ipv4`). | | `401` | `unauthorized` | Missing/invalid `Authorization` when `auth_header` is configured. | | `403` | `forbidden` | Source IP is not allowed by whitelist. | | `403` | `read_only` | Mutating endpoint called while `read_only=true`. | @@ -416,6 +420,7 @@ compatible; incompatible discovery changes require a new `schema_version`. | `rate_limit_down_bps` | `u64` | no | Per-user download rate limit in bits per second. | | `max_unique_ips` | `usize` | no | Per-user unique source IP limit. | | `enabled` | `bool` | no | User enable flag. Missing means enabled. `false` persists a disabled override. | +| `source_deny` | `string[]` or `null` | no | CIDR list; omission retains any orphan rule, null removes it. Generation reload required. | ### `PatchUserRequest` | Field | Type | Required | Description | @@ -430,20 +435,109 @@ compatible; incompatible discovery changes require a new `schema_version`. | `rate_limit_down_bps` | `u64` or `null` | no | Per-user download rate limit in bits per second; `null` removes the download direction limit. | | `max_unique_ips` | `usize` or `null` | no | Per-user unique source IP limit; `null` removes the per-user override. | | `enabled` | `bool` or `null` | no | `false` disables the user. `true` or `null` removes the disabled override, so the user is enabled. | +| `source_deny` | `string[]` or `null` | no | Replace the CIDR list; omission preserves it, null removes the entry. Generation reload required. | + +### Shared access policy + +`GET /v1/access/policy` and `PATCH /v1/access/policy` use the ordinary +administrative authorization and whitelist; mutations require `read_only=false`. +Both return `200` with `data.desired`, `data.effective`, `data.runtime` +(`active_generation`, `config_epoch`, `runtime_match`), `published_match`, +`effective_scope="active_config_snapshot"`, `subsystem_convergence="unknown"`, +`apply_mode="watcher"`, and the source-manifest `revision`. PATCH also returns +`changed_paths`. These snapshots do not acknowledge completion by every consumer. + +The policy contains exactly five fields: + +- `user_max_tcp_conns_global_each`: nonnegative per-user TCP default; `0` is unlimited. +- `user_max_unique_ips_global_each`: nonnegative per-user unique-IP default; `0` is unlimited. +- `user_max_unique_ips_mode`: `active_window`, `time_window`, or `combined`. +- `user_max_unique_ips_window_secs`: positive recent-IP window in seconds. +- `cidr_rate_limits`: a map of explicit IPv4/IPv6 CIDRs or `*4/N`, `*6/N`, `*/N` templates + to `{ "up_bps": ..., "down_bps": ... }`, in **bits per second**. + +Omission preserves a field. Scalar `null` removes its authored setting and restores +its type default. A non-null CIDR map merges entries: `null` removes that entry, +and a rate object replaces the whole pair (omitted directions become `0`, meaning +unlimited). At least one direction must be positive, and neither may exceed +`100000000000`. A whole-map `null` clears all CIDR rules. Empty patches are rejected. +Unknown fields, invalid prefixes/rates and duplicate normalized auto templates +return `400`. Explicit CIDRs retain longest-prefix precedence over auto templates; +`*/N` expands to IPv4 `/N` and IPv6 `/(N * 4)`. Existing bounded bursts are unchanged. + +```json +{ + "user_max_tcp_conns_global_each": 12, + "cidr_rate_limits": { + "192.0.2.0/24": {"up_bps": 8000000, "down_bps": 16000000}, + "*6/64": {"down_bps": 16000000}, + "203.0.113.0/24": null + } +} +``` + +Edits use the exact field's source owner, or the nearest existing parent for +insertion. Literal map keys are preserved. All changes in one request must belong +to one independently writable source; ambiguous or multiple owners return +`409 config_patch_not_atomic` without writing. The complete candidate is validated +before atomic replacement. Other source files remain unchanged; the owner is +edited structurally with comments retained where supported by the TOML editor. +Stale `If-Match` returns `409 revision_conflict`; stale `If-Runtime-Match` returns +`409 runtime_conflict`. Query parameters, including automatic reload, are rejected. +Users, credentials, replay limits and `ignore_time_skew` are outside this endpoint. +The legacy `PATCH /v1/config` still rejects the entire `access` section. + +`UserInfo.limits` contains `desired` and nullable `effective` snapshots for +`max_tcp_conns` and `max_unique_ips`. Each has `value` (null means unlimited), +`configured_override` (null means no authored entry), `global_value`, and `origin` +(`user_override`, `global_default`, `unlimited`). A zero user override inherits the +global default. `effective` is null when the user is absent from the sampled runtime +or no runtime snapshot was supplied. The scope is `active_config_snapshot` and +`subsystem_convergence` is `unknown`; legacy top-level limit fields retain their +desired-config fallback behavior. Policy edits do not cancel sessions or reset +quota usage; subsequent admission/publication follows existing runtime behavior. ### `access.user_source_deny` via API -- In current API surface, per-user deny-list is **not** exposed as a dedicated field in `CreateUserRequest` / `PatchUserRequest`. -- Configure it in `config.toml` under `[access.user_source_deny]` and apply via normal config reload path. -- Runtime behavior after apply: - - auth succeeds for username/secret - - source IP is checked against `access.user_source_deny[username]` - - on match, handshake is rejected with the same fail-closed outcome as invalid auth -Example config: -```toml -[access.user_source_deny] -alice = ["203.0.113.0/24", "2001:db8:abcd::/48"] -bob = ["198.51.100.42/32"] +User GET/create/PATCH expose `source_deny`, an IPv4/IPv6 CIDR array. Omission +preserves the existing rule, an array replaces the entire list (`[]` means no +denied networks), and explicit `null` removes that user's authored entry. +Strict configuration accepts `[access.user_source_deny]`. Malformed networks or +non-array values return `400` before writing. Changes to a username containing +dots edit that literal key, preserving other users' deny rows. + +`UserInfo.source_deny` is the desired list (empty when absent). +`source_deny_status` contains `effective` (the list in the sampled request +generation), `runtime_reload_required` (whether the lists differ), +`apply_mode="generation_reload"`, `effective_scope="request_generation_snapshot"`, +and `reload_endpoint="POST /v1/system/reload"`. Effective/reload fields are null +when no runtime snapshot is available. Existing `in_runtime` and HTTP `200/202` +only describe username membership; they do not prove deny-policy enforcement. + +After persistence, explicitly submit an instant or drain generation reload using +its returned source revision, then inspect reload status and the user's effective +list. The watcher does not overlay these rules. Saving a list does not cancel +sessions; retirement follows the selected reload mode. A reload that captured an +older revision may still activate that older policy: the desired/effective +comparison remains pending until a generation using the new revision is active. +This comparison does not describe still-draining older generations. + +User deletion retains source-deny rows. Recreating the same name with the field +omitted inherits the retained row, including a rule already present in runtime. +To remove it, PATCH `{"source_deny":null}` before deletion, or include +`"source_deny":null` when recreating the user; removal also needs generation +reload. A PATCH of a missing username still returns `404`. + +The mutation edits the exact owning source, or the nearest existing parent for +insertion. A request combining user-table and deny-rule changes in different +files returns `409 config_patch_not_atomic` and writes neither file. Source +revision fencing covers the entire include graph. After successful authentication, +the existing TLS/MTProto source check still rejects matching addresses through +the invalid-auth/fallback path without writing a protocol error or modifying the +original ClientHello. + +```json +{"source_deny":["203.0.113.0/24","2001:db8:abcd::/48"]} ``` ### `PatchConfigRequest` @@ -1664,6 +1758,9 @@ JA3 follows the Salesforce ClientHello field order. JA4 follows the FoxIO TLS-cl | `username` | `string` | Username. | | `enabled` | `bool` | Effective user enable flag. Missing config entry is reported as `true`. | | `in_runtime` | `bool` | Whether current runtime config already contains this user. | +| `limits` | `object` | Desired/published TCP and unique-IP limits with override/global/unlimited origins; see shared access policy. | +| `source_deny` | `string[]` | Desired source CIDRs; empty if no rule exists. | +| `source_deny_status` | `object` | Effective list and generation reload requirement; see source-deny contract. | | `user_ad_tag` | `string?` | Optional ad tag (32 hex chars). | | `max_tcp_conns` | `usize?` | Optional max concurrent TCP limit. | | `expiration_rfc3339` | `string?` | Optional expiration timestamp. | @@ -2036,7 +2133,7 @@ Applies a sparse patch to the editable config sections. The merged config is ful | `If-Match: ` | no | Optimistic concurrency. `` is the `revision` value from `GET /v1/config` or `config_hash` from `GET /v1/system/info`. It covers the complete recursive include graph. If supplied and it does not match the current source manifest, returns `409 revision_conflict`. Omitting it removes the caller precondition, but the internal graph/owner race fence can still return the same conflict. | | `If-Runtime-Match: ` | no | Token from `POST /v1/config/validate` or `GET /v1/config/state`, quoted or unquoted. A stale publication returns `409 runtime_conflict`; malformed/repeated headers return `400`. Even without it, active state is rechecked during preparation and immediately before the source rename. | -**Editable sections:** `general`, `timeouts`, `censorship`, `upstreams`, `dc_overrides`, `web`, plus partially editable `server` (only nested `listeners`) and `network` (only nested `dns_overrides`). +**Editable sections:** `general`, `timeouts`, `censorship`, `upstreams`, `dc_overrides`, `web`, plus partially editable `server` (`listeners` and five [API observability settings](#api-observability-settings)) and `network` (only nested `dns_overrides`). **Rejected keys and their error codes:** @@ -2045,7 +2142,7 @@ Applies a sparse patch to the editable config sections. The merged config is ful | `access` | `400` | `access_not_editable` | | Unknown top-level key or non-null, non-object `server`/`network` | `400` | `section_not_editable` | | `network` with keys other than `dns_overrides` (including null members) | `400` | `field_not_editable` | -| `server` with keys other than `listeners` | `400` | `field_not_editable` | +| `server` with keys other than `listeners`/`api`, or `server.api` with keys outside its five-field allowlist (including null members) | `400` | `field_not_editable` | | Object with no editable key | `400` | `bad_request` | | Unknown nested field or inapplicable variant field | `400` | `bad_request`, with `error.details` | @@ -2219,7 +2316,7 @@ Deployment, TLS-terminator examples, links, and WEB-specific verification are do | `POST /v1/users/{username}/enable` | Enables the user idempotently by removing the `access.user_enabled[username]` override and updating the runtime admission state immediately. | | `POST /v1/users/{username}/disable` | Disables the user idempotently by writing `access.user_enabled[username] = false`, updating runtime admission immediately, and cancelling active sessions for that username. | | `POST /v1/users/{username}/reset-quota` | Persists the quota checkpoint to `general.quota_state_path` before resetting live accounting for the route username; does not modify user config. | -| `DELETE /v1/users/{username}` | Deletes only the specified user, removes it from API-managed optional `access.user_*` maps, blocks last-user deletion, stages a deletion tombstone that cancels active owners, and atomically updates only related API-managed `access.*` TOML tables. It leaves `access.user_source_deny` untouched; manage that table manually in TOML. | +| `DELETE /v1/users/{username}` | Deletes only the specified user, removes it from API-managed optional `access.user_*` maps, blocks last-user deletion, stages a deletion tombstone that cancels active owners, and atomically updates only related API-managed `access.*` TOML tables. It leaves `access.user_source_deny` untouched; explicitly clear `source_deny` before deletion or during recreation, then reload the generation. | All accepted durable config, user, and quota mutations: - Respect `read_only` mode.