docs: access model, geodata lifecycle and one SSRF policy (C3)

api/auth.yaml

@@ -5,11 +5,13 @@ paths:
       summary: Create the administrator account and open a session
       description: >-
         Available only while discovery reports `auth.mode: password` with
-        `setup_required: true`. The peer must be loopback, RFC 1918, RFC 4193 or
+        `setup_required: true`. Checks run in this order: the Authorization
+        header, the peer, the account state, the body. A header that does not
+        carry a live session gets 401 `authentication_required`; before setup no
+        session exists. The peer must be loopback, RFC 1918, RFC 4193 or
         link-local; any other peer is refused with `permission_denied` before the
-        account state is read. Authorization must be absent: a request that
-        carries it is authenticated first, and before setup no session exists, so
-        it gets 401 `authentication_required`.
+        account state is read. After setup, the answer is 409
+        `setup_already_completed`, with or without a live session.
       security: []
       requestBody:
         required: true
@@ -66,9 +68,13 @@ paths:
       operationId: login
       summary: Exchange the administrator credentials for a session
       description: >-
-        Available only in password mode after setup. A wrong username or password
-        is `invalid_credentials`; before setup the answer is `setup_required`.
-        Authorization must be absent.
+        Available only in password mode after setup. Checks run in this order:
+        the Authorization header, the account state, the body. A header that does
+        not carry a live session gets 401 `authentication_required`; a live
+        session does not replace the body, which is still validated. Before setup
+        the answer is `setup_required`; a wrong username or password is
+        `invalid_credentials`. The engine may end a session before `expires_at`,
+        for example to stay within its session limit.
       security: []
       requestBody:
         required: true

api/common.yaml

@@ -627,7 +627,7 @@ schemas:
       message:
         type: string
         minLength: 1
-        description: Safe operator-facing description; never source excerpts, credentials, private paths, or raw engine errors.
+        description: Safe operator-facing description; never source excerpts, listener secrets or raw engine errors. See the visibility table in api-config.
   ConfigDiagnosticSpan:
     type: object
     required: [ start_line, start_column, end_line, end_column ]

api/config.yaml

@@ -8,8 +8,8 @@ paths:
         accepted sources and retained diagnostics for generation_id and revision,
         not a fresh read of files that may have changed since loading. The source
         set is complete and bounded by resources.config.max_sources; never truncate it.
-        Every source carries its content. Apply visibility filters to paths,
-        content and diagnostics; observe never grants raw secrets.
+        Every source carries its content. Paths, content and diagnostics follow
+        the visibility table in api-config: only listener-secret values are masked.
       x-permission: observe
       security:
         - bearerAuth: []
@@ -420,8 +420,8 @@ paths:
       summary: Read one accepted configuration source
       description: |
         Requires resources.config.available. Returns the same ConfigSource as
-        GET /config, not a fresh read of the store, with its content; apply the
-        same path and secret redaction.
+        GET /config, not a fresh read of the store, with its content; mask listener
+        secrets as in GET /config.
         Unknown source IDs return 404 resource_not_found. Redacted text must never
         be saved as a replacement; compare its UTF-8 SHA-256 with content_sha256
         before using returned content as an editing representation.
@@ -777,7 +777,7 @@ paths:
         including locally resolved source text in full mode; exceeding either returns
         413. Geodata assets do not count toward the byte limit.
         The shared max_json_body_bytes limit applies independently to the HTTP body.
-        Never echo candidate text, secrets, or private paths in diagnostics or errors.
+        Never echo candidate text or listener secrets in diagnostics or errors.
       x-permission: control
       security:
         - bearerAuth: []
@@ -1179,7 +1179,7 @@ schemas:
         description: True when validation completes without error diagnostics. Successful validation does not guarantee a later apply will succeed.
       diagnostics:
         type: array
-        description: Source IDs identify submitted sources. Attribute a dependency failure to the referring submitted source and its include/subscription location, not an undisclosed local path.
+        description: Source IDs identify submitted sources. Attribute a dependency failure to the referring submitted source and its include/subscription location.
         items:
           $ref: ./openapi.yaml#/components/schemas/ConfigDiagnostic
       generation_id:

api/discovery.yaml

@@ -85,7 +85,7 @@ paths:
     get:
       operationId: getVersion
       summary: Read native and engine version identity
-      description: Requires bearer authentication when the listener has a deployment secret. Anonymous access is permitted only on an explicitly secretless loopback listener. No resource permission is required.
+      description: Requires bearer authentication when the listener has a deployment secret or runs in password mode. Anonymous access is permitted only on an explicitly secretless loopback listener. No resource permission is required.
       security:
         - bearerAuth: []
         - {}
@@ -131,7 +131,7 @@ paths:
     get:
       operationId: getCapabilities
       summary: Negotiate resources, visibility, and limits
-      description: Requires bearer authentication when the listener has a deployment secret. Anonymous access is permitted only on an explicitly secretless loopback listener. No resource permission is required.
+      description: Requires bearer authentication when the listener has a deployment secret or runs in password mode. Anonymous access is permitted only on an explicitly secretless loopback listener. No resource permission is required.
       security:
         - bearerAuth: []
         - {}
@@ -288,6 +288,10 @@ paths:
                         can_update: true
                         assets: [ geosite, geoip ]
                         configurable_sources: true
+                        max_urls: 4
+                        interval_hours: { min: 6, max: 168, default: 24 }
+                        checksum: sha256sum
+                        lifecycle: { file_values: start, overrides_persist: true }
                       operations:
                         available: true
                         retention_seconds: 300
@@ -1033,12 +1037,27 @@ schemas:
           geodata:
             type: object
             required: [ available ]
-            if:
-              properties:
-                available:
-                  const: true
-            then:
-              required: [ can_update, assets ]
+            allOf:
+              - if:
+                  properties:
+                    available:
+                      const: true
+                then:
+                  required: [ can_update, assets ]
+              - if:
+                  required: [ can_update ]
+                  properties:
+                    can_update:
+                      const: true
+                then:
+                  required: [ checksum ]
+              - if:
+                  required: [ configurable_sources ]
+                  properties:
+                    configurable_sources:
+                      const: true
+                then:
+                  required: [ max_urls, interval_hours, checksum, lifecycle ]
             properties:
               available:
                 type: boolean
@@ -1054,6 +1073,42 @@ schemas:
               configurable_sources:
                 type: boolean
                 description: Download URLs and automatic updates are managed through geodata in GET and PATCH /runtime/settings, and GET /geodata reports update status and required_codes. Requires runtime_settings.available with geodata in its fields. Absent means false.
+              max_urls:
+                type: integer
+                minimum: 1
+                description: Most download URLs per asset a geodata patch may set. Required when configurable_sources is true.
+              interval_hours:
+                type: object
+                additionalProperties: false
+                required: [ min, max, default ]
+                description: Bounds and default of geodata auto_update.interval_hours. Required when configurable_sources is true. min <= default <= max is required; JSON Schema cannot express this ordering, so validators check it separately.
+                properties:
+                  min:
+                    type: integer
+                    minimum: 1
+                  max:
+                    type: integer
+                    minimum: 1
+                  default:
+                    type: integer
+                    minimum: 1
+              checksum:
+                type: [ string, "null" ]
+                enum: [ sha256sum, pinned, null ]
+                description: How the backend verifies a download when verify_checksum is true. sha256sum appends .sha256sum to the URL path, keeping any query, and compares the SHA-256 the response names; a 404 means none is published. pinned compares with a SHA-256 the backend holds for the URL. Null means downloads are unverified. Required when can_update or configurable_sources is true.
+              lifecycle:
+                type: object
+                additionalProperties: false
+                required: [ file_values, overrides_persist ]
+                description: When geodata settings take configuration-file values and how long overrides last; see Geodata. Required when configurable_sources is true.
+                properties:
+                  file_values:
+                    type: string
+                    enum: [ start, activation ]
+                    description: start takes file values at process start only; activation also takes them at each configuration activation.
+                  overrides_persist:
+                    type: boolean
+                    description: True when a PATCH override lasts across restarts; false when it lasts until the process exits.
           operations:
             type: object
             required: [ available ]

api/dns.yaml

@@ -524,7 +524,7 @@ paths:
                         action: upstream
                         upstream: alidns
                         source:
-                          file: "[redacted]/config.dae"
+                          file: config.dae
                           source_id: source-main
                           line: 40
                           column: 7
@@ -535,7 +535,7 @@ paths:
                         action: reject
                         upstream: null
                         source:
-                          file: "[redacted]/config.dae"
+                          file: config.dae
                           source_id: source-main
                           line: 41
                           column: 7
@@ -546,7 +546,7 @@ paths:
                         action: upstream
                         upstream: googledns
                         source:
-                          file: "[redacted]/config.dae"
+                          file: config.dae
                           source_id: source-main
                           line: 42
                           column: 7
@@ -558,7 +558,7 @@ paths:
                         action: requery
                         upstream: alidns
                         source:
-                          file: "[redacted]/config.dae"
+                          file: config.dae
                           source_id: source-main
                           line: 45
                           column: 7

api/flows.yaml

@@ -952,7 +952,7 @@ schemas:
         description: Generation-scoped traffic rule ID, or null when unavailable.
       rule_expression:
         type: [ string, "null" ]
-        description: Sanitized display expression for that rule, or null when unavailable.
+        description: Display expression for that rule, or null when unavailable.
       rule_source:
         type: string
         enum: [ kernel, recomputed, unknown ]
@@ -1092,7 +1092,7 @@ schemas:
         description: Generation-scoped traffic rule ID, or null when unavailable.
       rule_expression:
         type: [ string, "null" ]
-        description: Sanitized display expression for that rule, or null when unavailable.
+        description: Display expression for that rule, or null when unavailable.
       rule_source:
         type: string
         enum: [ kernel, recomputed, unknown ]