Big bunch of documentation fixes

Author: Aitem

docs/SUMMARY.md

@@ -254,6 +254,7 @@
     * [Patient data access API](access-control/authorization/scoped-api/patient-data-access-api.md)
   * [Label-based Access Control](access-control/authorization/label-based-access-control.md)
 * [Audit and Logging](access-control/audit-and-logging.md)
+* [Security Hardening](access-control/security-hardening.md)
 
 ## Artifact Registry
 

docs/access-control/authorization/label-based-access-control.md

@@ -47,6 +47,10 @@ securityLabel:
     code: M
 ```
 
+{% hint style="warning" %}
+**User.securityLabel and Bearer tokens**: Labels from `User.securityLabel` are applied only when the user is identified via **cookie-based session** (e.g. form login in the Aidbox UI). When the request uses a **Bearer token** (e.g. from Resource Owner Password Credentials or an opaque token), Aidbox does not look up the User's `securityLabel`; those sessions do not carry user labels. For API access with LBAC, use **JWT tokens** that include security labels in the `scope` claim (format `system|code`), as described in the **scope claim in JWT** section above.
+{% endhint %}
+
 ### Expanding confidentiality security label
 
 The security label for confidentiality is [hierarchical](https://terminology.hl7.org/ValueSet-v3-Confidentiality.html). The code may contain several others.
@@ -173,9 +177,13 @@ subject:
 To prevent security labels from appearing in the outcome, set the `strip labels` env:
 
 ```yaml
-BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS=true
+BOX_SECURITY_LBAC_STRIP_LABELS=true
 ```
 
+{% hint style="info" %}
+The legacy name `BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS` is deprecated but still supported. See [all-settings](../../../reference/all-settings.md#security.lbac.strip-labels).
+{% endhint %}
+
 **Stripping examples**
 
 The security labels from `meta.security` and `_status` fields have been removed from the outcome.

docs/access-control/security-hardening.md

@@ -0,0 +1,60 @@
+---
+description: CORS, security headers, cookies, session management, and infrastructure security for Aidbox.
+---
+
+# Security Hardening
+
+This page describes infrastructure-level security features in Aidbox: CORS, security headers, cookie flags, session management, and what is not implemented. Use it together with [Access Policies](authorization/access-policies.md), [Audit and Logging](audit-and-logging.md), and [User management](identity-management/user-management.md) for a complete security picture.
+
+## CORS
+
+Cross-Origin Resource Sharing (CORS) is **enabled by default**. Aidbox supports:
+
+* **Wildcard mode** — `BOX_SECURITY_CORS_ORIGINS=*` (default). Any `Origin` header is echoed back in `Access-Control-Allow-Origin`. Use only in development or when all origins are trusted.
+* **Whitelist mode** — Set `BOX_SECURITY_CORS_ORIGINS` to a comma-separated list of origins, e.g. `https://app.example.com,https://trusted.example.com`. Only those origins receive CORS headers; requests from other origins get no `Access-Control-*` headers (but the API still responds).
+* **Disabled** — Set `BOX_SECURITY_CORS_ENABLED=false` to disable CORS entirely.
+
+Preflight `OPTIONS` requests are handled: allowed methods and requested headers are reflected in `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers`. Credentials are supported (`Access-Control-Allow-Credentials: true`). Settings can be changed at runtime via the [Settings API](../reference/all-settings.md) (or environment variables).
+
+See [security.cors.enabled](../reference/all-settings.md#security.cors.enabled) and [security.cors.origins](../reference/all-settings.md#security.cors.origins).
+
+## Cookie security
+
+Session cookies set by Aidbox (e.g. after login) use:
+
+* **HttpOnly** — set, to reduce XSS-based cookie theft
+* **SameSite=Lax** — set, to reduce CSRF from cross-site requests
+
+The **Secure** flag is not set by Aidbox. When Aidbox is behind HTTPS (e.g. reverse proxy), consider configuring the proxy or application to set `Secure` on cookies if your deployment supports it.
+
+## Session and token management
+
+* **Session expiration** — Default session (cookie) lifetime is configurable (e.g. via AuthConfig). Expired sessions are cleaned up automatically.
+* **Access token expiration** — Configurable per [Client](identity-management/application-client-management.md) (e.g. `auth.client_credentials.access_token_expiration`). Tokens are rejected after expiry (401).
+* **Sessions list** — Active sessions can be inspected via the `Session` resource (if available in your setup).
+
+See [OAuth 2.0](authentication/oauth-2-0.md) and [Client management](identity-management/application-client-management.md).
+
+## What is not implemented
+
+The following are **not** implemented in Aidbox. Rely on operational measures or reverse proxy where needed:
+
+| Feature | Description |
+|--------|-------------|
+| **Rate limiting** | No request throttling on API or auth endpoints. Use a reverse proxy or WAF for rate limiting. |
+| **Brute-force protection** | No automatic account lockout after failed login attempts. Use the [User.inactive](../tutorials/security-access-control-tutorials/prohibit-user-to-login.md) flag to lock accounts manually, or implement throttling at the proxy. |
+| **HSTS** | Header not set. Add at reverse proxy when using HTTPS. |
+| **X-Content-Type-Options / Referrer-Policy** | Not set. Add at reverse proxy for defense in depth. |
+
+## Infrastructure recommendations
+
+* **TLS** — Terminate TLS at a reverse proxy or load balancer. Do not expose Aidbox directly to the internet without encryption.
+* **Reverse proxy** — Use nginx, Traefik, or similar to add security headers (HSTS, X-Content-Type-Options, Referrer-Policy), rate limiting, and DDoS mitigation.
+* **Network** — Restrict access to Aidbox and the database to trusted networks where possible.
+
+## See also
+
+* [All settings (CORS, CSP)](../reference/all-settings.md) — `security.cors.*`, `security.content-security-policy-header`
+* [Audit and Logging](audit-and-logging.md)
+* [User management](identity-management/user-management.md) — password and lockout
+* [Prohibit user to login](../tutorials/security-access-control-tutorials/prohibit-user-to-login.md) — manual lockout via `User.inactive`

docs/api/bulk-api/dump-sql.md

@@ -6,7 +6,11 @@ description: Export SQL query results as CSV or ndjson stream using $dump-sql op
 
 ## Dump results of the sql query
 
-`$dump-sql` operation takes the sql query and responds with the Chunked Encoded stream in CSV format or in NDJSON format. Useful to export data for analytics.
+`$dump-sql` operation takes the sql query and responds with the Chunked Encoded stream in TSV format (default) or in JSON/NDJSON format. Useful to export data for analytics.
+
+{% hint style="warning" %}
+**Streaming and errors**: The response is streamed. If the SQL is invalid or the request body is missing or malformed, the server may still return **HTTP 200** and write error text into the response body instead of returning 4xx with an OperationOutcome. Check the response body for error messages when the output is unexpected.
+{% endhint %}
 
 ```typescript
 POST [base]/$dump-sql

docs/api/bulk-api/export.md

@@ -12,6 +12,8 @@ Export operations run one at a time to prevent resource exhaustion. If you attem
 
 ## Cloud storage setup
 
+$export requires cloud storage to be configured. If no storage provider is set, export requests (system-, group-, or patient-level) return **500** with an error such as "storage-type not specified". Storage validation is performed before other checks (e.g. group existence or output format).
+
 Aidbox exports data to cloud storage backends including GCP, Azure, and AWS. Export files are organized in timestamped folders with the pattern `<datetime>_<uuid>` to ensure unique paths for each export operation.
 
 Each cloud provider supports two authentication modes: credential-based (using stored keys or tokens) and workload identity (using cloud-native pod identity). Workload identity is recommended for managed Kubernetes deployments (GKE, AKS) as it eliminates the need to manage credentials in Aidbox resources and uses the pod's identity to authenticate with cloud storage.

docs/api/bulk-api/purge.md

@@ -16,6 +16,10 @@ This operation implements the [FHIR Patient Purge](https://build.fhir.org/patien
 **Idempotent**: Purging a non-existent patient returns 200 (sync) or 202 (async) without error. This allows re-running `$purge` after a partial failure.
 {% endhint %}
 
+{% hint style="info" %}
+**After purge**: Purged resources are permanently removed. Requests to read them return **404 Not Found** (not 410 Gone), since the resources no longer exist.
+{% endhint %}
+
 {% hint style="warning" %}
 **Scoped references**: Only resources that reference the patient with the full reference format (e.g., `Patient/<id>`) are deleted. Resources referencing a different resource type with the same ID are not affected.
 {% endhint %}
@@ -32,7 +36,9 @@ POST /fhir/Patient/<patient-id>/$purge
 
 ## Parameters
 
-The request body is optional. When provided, it must be a `Parameters` resource with the following optional parameter:
+The request body is optional. When provided, it must be a FHIR `Parameters` resource (e.g. `{"resourceType": "Parameters"}`). An empty JSON body `{}` is rejected with **422** and "Request body must be a Parameters resource". Omit the body or send `{"resourceType": "Parameters"}` when no custom parameters are needed.
+
+Optional parameter:
 
 | Parameter                | Type                   | Description                                                                                                                                                                   |
 | ------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

docs/api/rest-api/fhir-search/README.md

@@ -154,7 +154,7 @@ List of supported modifiers:
 | :not               | token                 | Negates the search value                                                                                                                             | `gender:not=male`                                     |
 | :of-type           | token                 | Search for resource identifier                                                                                                                       | `identifier:of-type=system`                           |
 | :i                 | token                 | Case-insensitive search                                                                                                                              | `email:[email protected]`                                 |
-| :below             | uri                   | Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships)                        | `url:below=http://acme.org/fhir/`                     |
+| :below             | uri                   | Not supported for **url** parameter (ValueSet, CodeSystem, etc.) — returns 500. See [uri](searchparameter.md#uri).                                      | `_source:below=` supported; `url:below=` returns 500                                   |
 | :not               | uri, reference, token | Negates the search value                                                                                                                             | `url:not=http://acme.org/fhir/`                       |
 | :identifier        | reference             | Search by identifier of referenced resource                                                                                                          | `subject:identifier=urn:oid:1.2.3.4`                  |
 | :btw               | date                  | Search for dates between two values. Defined by Aidbox, not FHIR.                                                                                    | `birthdate:btw=1980,1981`                             |
@@ -201,6 +201,14 @@ See also:
 [chaining.md](chaining.md)
 {% endcontent-ref %}
 
+## Known limitations
+
+| Feature | Limitation |
+|--------|-------------|
+| **Quantity search with unit** | Specifying a unit in the value (e.g. `value-quantity=75.5\|\|kg`) is not implemented; returns 400. Only numeric value comparison is supported. See [quantity](searchparameter.md#quantity). |
+| **url :below modifier** | The `:below` modifier for the **url** search parameter (ValueSet, CodeSystem, StructureDefinition) is not supported; returns 500. `_source:below` works. See [uri](searchparameter.md#uri). |
+| **Component-level composite** | `component-code-value-quantity` (and similar component composites) may not return results; top-level composite search works. See [composite](searchparameter.md#composite). |
+
 ## Other ways to search
 
 Sometimes FHIR Search API is not enough. For example, there's no way to search using a case-insensitive match without starts-with **string** type logic (combining token and string types), which is useful to search, say, for domains of emails. 

docs/api/rest-api/fhir-search/searchparameter.md

@@ -125,7 +125,7 @@ Token searches support these modifiers:
 | :in      | Search within a ValueSet                                                                                                                          | `code:in=/ValueSet/test-codes` |
 | :i       | Case-insensitive search                                                                                                                           | `code:i=TEST123`               |
 | :not     | Negates the search value                                                                                                                          | `code:not=inactive`            |
-| :of-type | Search for resource identifier                                                                                                                    | \`identifier:of-type=system    |
+| :of-type | Search for resource identifier                                                                                                                    | `identifier:of-type=system`    |
 
 ### uri
 
@@ -143,9 +143,12 @@ URI searches support these modifiers:
 | Modifier | Description                                                                                                                   | Example                           |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
 | :missing | Matches resources that do not have a value in the field                                                                       | `url:missing=true`                |
-| :below   | Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships) | `url:below=http://acme.org/fhir/` |
 | :not     | Negates the search value                                                                                                      | `url:not=http://example.com`      |
 
+{% hint style="warning" %}
+The **:below** modifier is not supported for the **url** search parameter (e.g. on ValueSet, CodeSystem, StructureDefinition). Queries such as `ValueSet?url:below=http://hl7.org` return 500 with "Unsupported search parameter 'url:below'". Other URI-type parameters (e.g. `_source`) may accept `:below`.
+{% endhint %}
+
 ### reference
 
 Reference search parameters match against references to other resources. They are used to search for resources that reference a specific resource.
@@ -240,8 +243,8 @@ Quantity search parameters match against values with units. They support the sam
 | ne     | Not equal       | `weight=ne100` |
 | gt     | Greater than    | `weight=gt100` |
 
-However, Aidbox supports only numbers, not system with code.\
-For example, `weight=100` will match resources with `weight` exactly equal to "100", the unit is ignored.
+However, Aidbox supports only numeric value comparison; unit specification is not implemented.\
+For example, `value-quantity=75.5` matches by value only. Using a unit in the search value (e.g. `value-quantity=75.5\|\|kg`) returns **400** with the message "quantity with unit specified is not implemented".
 
 ### composite
 
@@ -281,6 +284,10 @@ GET /fhir/Observation?code=loinc|12907-1&value-quantity=1 // found
 GET /fhir/Observation?code=loinc|12907-1&value-quantity=2 // found
 ```
 
+{% hint style="info" %}
+**Component-level composite**: Top-level composite search (e.g. `code-value-quantity`) works as described. The `component-code-value-quantity` parameter (matching on Observation.component) may not return results for component-level matching; this is a known limitation.
+{% endhint %}
+
 ### special
 
 Special search parameters have unique search behavior that cannot be expressed using the standard search parameter types. The behavior of special search parameters must be explicitly defined in their SearchParameter definition. Special parameters are useful for cases where the standard parameter types (string, token, reference, etc.) cannot adequately express the desired search functionality.