@kollors/deep-json-server 1.0.0-alpha.4 → 1.0.0-alpha.6

package/README.md

@@ -4,7 +4,7 @@
 
 A JSON-backed mock server with REST, GraphQL, nested queries, binary files and schema exports. Requires Node.js 22 or newer.
 
-**1.0.0-alpha.4 is a prerelease.** When upgrading from 0.x, update your model schema and query parameters using the examples below.
+**1.0.0-alpha.6 is a prerelease.** REST queries use `scope=[fields, arguments?]` at every level. When upgrading from an earlier version, update query parameters using the examples below; upgrading from 0.x also requires the new model schema.
 
 ## Installation
 
@@ -12,7 +12,7 @@ A JSON-backed mock server with REST, GraphQL, nested queries, binary files and s
 npm install @kollors/deep-json-server@alpha
 ```
 
-To install a specific version, use `@1.0.0-alpha.4`.
+To install a specific version, use `@1.0.0-alpha.6`.
 
 ## Quick start
 
@@ -55,6 +55,9 @@ The user list is available at `http://127.0.0.1:4001/users`.
 | `graphql.enabled` | Enable GraphQL HTTP endpoint; default `false` |
 | `graphql.endpoint` | Endpoint path; default `/graphql` |
 | `graphql.path` | GraphQL SDL export destination |
+| `auth.enabled` | Enable authentication; default `false` |
+| `auth.users` | Path to a JSON array of auth users, or an in-memory array |
+| `auth.expiresIn` | Session lifetime in seconds; default 3600 |
 | `server.host`, `server.port` | Defaults `127.0.0.1`, `4001`; CLI also reads `HOST`/`PORT` |
 | `server.pageSize`, `server.maxPageSize` | Defaults 10 and 100; default size is capped by the maximum |
 | `server.cors`, `server.logger` | Default `true`; logger also accepts Fastify logger options |
@@ -71,6 +74,7 @@ Set `server.port` to `0` to let the operating system choose an available port. T
 | `--files` | Enable file routes |
 | `--graphql` | Enable the GraphQL API |
 | `--openapi` | Enable the OpenAPI endpoint |
+| `--auth` | Enable authentication using `auth.users` |
 | `--host <host>` | Server address |
 | `--port <port>` | Server port |
 | `--help`, `-h` | Show help |
@@ -96,7 +100,7 @@ export default {
 };
 ```
 
-Each format needs its own output file. The command rejects destinations that would overwrite the configuration, database, schema or file metadata.
+Each format needs its own output file. The command rejects destinations that would overwrite the configuration, database, schema, auth users or file metadata.
 
 ## Model schema
 
@@ -136,7 +140,7 @@ Examples: [database](examples/database.json), [model schema](examples/schema.jso
 
 Explicit schemas are strict: undeclared fields and collections are rejected, except storage keys inferred from relations. Existing data is validated on startup. Generation uses the model definitions.
 
-Schemaless REST generates an `id` and preserves arbitrary JSON fields. Filters and individual field selections use identifier-style names; other fields are returned through `scope={"*":true}`. Fields with mixed value types can be read, but using them in `where`, `order` or `nested` requires an explicit schema.
+Schemaless REST generates an `id` and preserves arbitrary JSON fields. Filters and individual field selections use identifier-style names; other fields are returned through `scope=[{"*":true}]`. Fields with mixed value types can be read, but filtering, ordering and paging heterogeneous lists require an explicit schema.
 
 ### Fields
 
@@ -288,51 +292,59 @@ mutation {
 
 ### REST query parameters
 
-Query parameters `where`, `order`, `pager`, `nested` and `scope` contain JSON. Example shown before URL encoding:
+REST accepts one query parameter, `scope`, containing a JSON array `[fields, arguments?]`. The first object selects fields; the optional second object supplies `where`, `order` and `pager` for a list. The same format applies to the root query, embedded objects and relations.
 
-```text
-GET /users?where={"fullName":{"contains":"Мира"}}&order=[{"field":"fullName","direction":"ASC"}]&pager={"page":1,"pageSize":20}
-```
-
-Construct encoded URLs with `URLSearchParams`:
+Select users and their movies with independent ordering and pagination:
 
 ```js
-const params = new URLSearchParams({
-  scope: JSON.stringify({ id: true, fullName: true, movies: { id: true, title: true } }),
-  nested: JSON.stringify({ movies: { order: [{ field: 'title', direction: 'ASC' }], pager: { page: 1, pageSize: 5 } } }),
-});
+const scope = [
+  {
+    id: true,
+    fullName: true,
+    movies: [
+      { id: true, title: true },
+      {
+        order: [{ field: 'title', direction: 'ASC' }],
+        pager: { page: 1, pageSize: 5 },
+      },
+    ],
+  },
+  {
+    where: { fullName: { contains: 'Мира' } },
+    order: [{ field: 'fullName', direction: 'ASC' }],
+    pager: { page: 1, pageSize: 20 },
+  },
+];
+const params = new URLSearchParams({ scope: JSON.stringify(scope) });
 const response = await fetch(`/users?${params}`);
 ```
 
-`scope` selects fields in the response:
+Select ordinary fields with `true` and objects or relations with their own scope arrays. Without arguments, the array contains only the fields object. `"*": true` includes own fields and stored keys, except `writeOnly` fields; select relations explicitly.
+
+For example, select a movie's own fields, its actors' users and sorted genres:
 
 ```json
-{
-  "*": true,
-  "actors": {
-    "user": { "id": true, "fullName": true },
-    "genres": { "*": true }
+[
+  {
+    "*": true,
+    "actors": [
+      {
+        "user": [{ "id": true, "fullName": true }],
+        "genres": [
+          { "*": true },
+          { "order": [{ "field": "name", "direction": "ASC" }] }
+        ]
+      }
+    ]
   }
-}
+]
 ```
 
-`true` includes a field; an object selects fields inside an object or relation. `"*": true` includes own fields and stored keys, except `writeOnly` fields. Relations are listed explicitly. Setting a relation to `true` selects its own fields.
+Omitting `scope` returns own fields, as with `[{"*":true}]`. An empty selection `[{}]` returns an object without fields. Lists retain the `{ data, total }` response structure.
 
-Omitting `scope` selects own fields. `{}` selects no fields. Values must be `true` or nested objects; `false`, `null` and arrays return `400`. Lists retain the `{ data, total }` response structure.
+Arguments are available only on lists. Single-record queries and mutation responses can set arguments on their embedded lists. Parameters are validated even on empty data; an invalid response selection rolls back record changes. Invalid scopes return `400`. The JSON length limit is 10,000 characters; selection depth is limited to 32 levels.
 
-`nested` maps full response paths to list options:
-
-```json
-{
-  "actors": { "pager": { "pageSize": 5 } },
-  "actors.genres": {
-    "where": { "id": { "in": ["2", "3"] } },
-    "order": [{ "field": "name", "direction": "ASC" }]
-  }
-}
-```
-
-A path in `nested` must be selected by `scope` and point to an object list. Single-record routes and mutations accept `scope` and `nested`; root `where`, `order` and `pager` apply to collection GET. Invalid names and unsafe paths return `400`.
+OpenAPI remains at version 3.0.3. It cannot define a separate schema for each array position: the documentation describes the elements, and the server strictly validates their order.
 
 ### GraphQL
 
@@ -526,10 +538,48 @@ Content-Type: application/json
 
 In disk mode, the binary is stored at `<files.directory>/<directory>/<name>`. Metadata stores `directory`, `mimeType` and `name`; the server reads the size from the file and builds its URLs. Directories and the metadata file are created when needed.
 
-Use one server process per disk database and file store. Stop it before editing stored files or metadata manually. Storage paths cannot contain symbolic links. Uploads and renames cannot overwrite the database, counters, schema, loaded configuration or metadata file.
+Use one server process per disk database and file store. Stop it before editing stored files or metadata manually. Storage paths cannot contain symbolic links. Uploads and renames cannot overwrite the database, counters, schema, auth users, loaded configuration or metadata file.
 
 Send the file as a binary request body. In a browser, use `xhr.send(file)` and track progress through `XMLHttpRequest.upload.onprogress`. The default maximum size is 100 MiB and can be changed through `server.maxFileSize`. Missing or unsafe headers and paths return `400`, an exceeded limit returns `413`, and a missing, malformed, or Fastify-unsupported `Content-Type` returns `400` or `415`, depending on which validation stage rejects it.
 
+## Authentication
+
+The optional auth module provides REST routes for login, current user and logout. **It does not restrict access to REST records, files or GraphQL.**
+
+Create an auth user in a separate file with `setup-auth.mjs`:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { hashPassword } from '@kollors/deep-json-server/auth';
+
+const password = process.env.DJS_PASSWORD;
+if (!password) throw new Error('Set DJS_PASSWORD');
+await writeFile('./auth.json', JSON.stringify([
+  { id: '1', username: 'admin', passwordHash: await hashPassword(password) },
+], null, 2), { flag: 'wx', mode: 0o600 });
+```
+
+Set `DJS_PASSWORD` and run `node setup-auth.mjs`. Add the file to your server configuration:
+
+```js
+export default {
+  database: { path: './database.json' },
+  auth: { users: './auth.json', expiresIn: 3600 },
+};
+```
+
+Start with `npx deep-json-server --auth server.config.js`, or set `auth.enabled: true`. Each user needs a unique string `id`, a unique `username` and a `passwordHash` created by the helper. Passwords use salted scrypt hashes. The file is read at startup; restart the server after editing it.
+
+| REST request | Input | Response |
+|---|---|---|
+| `POST /auth/login` | JSON `{ "username": "admin", "password": "…" }` | `{ accessToken, expiresIn, user: { id, username } }` |
+| `GET /auth/me` | Bearer token | `{ id, username }` |
+| `POST /auth/logout` | Bearer token | `{ success: true }` |
+
+Pass the token in `Authorization: Bearer <accessToken>`. Incorrect credentials and invalid or expired tokens return HTTP 401. Sessions are kept in memory and disappear on restart; logout revokes the supplied token. Login can return HTTP 429 when the server has too many concurrent login attempts or active sessions.
+
+OpenAPI includes these REST operations and a Bearer security scheme for `/auth/me` and `/auth/logout`. In Swagger UI, paste a token from login into **Authorize**. For schema exports, enable auth in the configuration or use `generate openapi --auth server.config.js`; the users file is not read during generation. GraphQL and OpenAPI still require `database.schema`.
+
 ## Programmatic API
 
 ```js
@@ -542,7 +592,7 @@ await server.listen();
 // await server.close();
 ```
 
-The `openapi()` and `graphql()` methods return schemas and require `database.schema`. `fastify()` returns the server instance for configuration and startup. The database and enabled services initialize on `ready()`, `listen()` or the first `inject()`; initialization errors stop startup. Override server features with `createServer(config, { files: false, graphql: true, openapi: true })`.
+The `openapi()` and `graphql()` methods return schemas and require `database.schema`. `fastify()` returns the server instance for configuration and startup. The database and enabled services initialize on `ready()`, `listen()` or the first `inject()`; initialization errors stop startup. Override server features with `createServer(config, { files: false, graphql: true, openapi: true, auth: true })`.
 
 The root import `@kollors/deep-json-server` also provides these functions. Server adapters load when enabled. Generators can be used independently:
 
@@ -556,13 +606,15 @@ await writeOpenapi(document, './generated/openapi.yaml');
 await writeGraphql(sdl, './generated/schema.graphql');
 ```
 
+`generateOpenapi()` accepts `{ auth: true }` to include auth operations. `hashPassword()` is also available from the root package.
+
 `generateOpenapi()` also accepts `host`, `port`, `pageSize`, `maxPageSize` and `info`. Pass a schema object instead of a path if preferred. Servers and generators use their own copy of the model. Pagination sizes must be positive integers; `pageSize` cannot exceed `maxPageSize`.
 
 ## Storage and development
 
 Updates run sequentially within one server instance and are validated on a copy of the data before saving. Use one server process per database file. `increment` counters are stored next to the database in `<database path>.counters.json`; keep that file with the database. Numbers are reserved before the data write, so a failed write can leave gaps but cannot reuse a reserved number.
 
-The server is intended for mocking APIs. Implement authentication and password hashing in your application if needed.
+The server is intended for mocking APIs. Access rules for application data remain the responsibility of your application.
 
 ```sh
 npm ci

package/README.ru.md

@@ -4,7 +4,7 @@
 
 JSON-сервер для имитации API: REST, GraphQL, вложенные запросы, бинарные файлы и экспорт схем. Требуется Node.js 22 или новее.
 
-**1.0.0-alpha.4 — предварительная версия.** При переходе с 0.x обновите схему моделей и параметры запросов по примерам ниже.
+**1.0.0-alpha.6 — предварительная версия.** REST-запросы используют `scope=[поля, аргументы?]` на всех уровнях. При обновлении измените параметры запросов по примерам ниже; для перехода с 0.x также нужна новая схема моделей.
 
 ## Установка
 
@@ -12,7 +12,7 @@ JSON-сервер для имитации API: REST, GraphQL, вложенные
 npm install @kollors/deep-json-server@alpha
 ```
 
-Для установки конкретной версии укажите `@1.0.0-alpha.4`.
+Для установки конкретной версии укажите `@1.0.0-alpha.6`.
 
 ## Быстрый старт
 
@@ -55,6 +55,9 @@ npx deep-json-server server.config.js
 | `graphql.enabled` | Включить GraphQL HTTP API; по умолчанию `false` |
 | `graphql.endpoint` | Путь GraphQL; по умолчанию `/graphql` |
 | `graphql.path` | Путь экспорта GraphQL SDL |
+| `auth.enabled` | Включить аутентификацию; по умолчанию `false` |
+| `auth.users` | Путь к JSON-массиву учётных записей или массив в памяти |
+| `auth.expiresIn` | Срок действия сессии в секундах; по умолчанию 3600 |
 | `server.host`, `server.port` | По умолчанию `127.0.0.1`, `4001`; CLI также читает `HOST`/`PORT` |
 | `server.pageSize`, `server.maxPageSize` | По умолчанию 10 и 100; размер по умолчанию ограничен максимумом |
 | `server.cors`, `server.logger` | По умолчанию `true`; logger также принимает настройки Fastify |
@@ -71,6 +74,7 @@ npx deep-json-server server.config.js
 | `--files` | Включить файловые маршруты |
 | `--graphql` | Включить GraphQL API |
 | `--openapi` | Включить HTTP-маршрут OpenAPI |
+| `--auth` | Включить аутентификацию с учётными записями из `auth.users` |
 | `--host <host>` | Адрес сервера |
 | `--port <port>` | Порт сервера |
 | `--help`, `-h` | Справка |
@@ -96,7 +100,7 @@ export default {
 };
 ```
 
-Для каждого формата нужен отдельный файл. Команда отклонит путь, который перезапишет конфигурацию, базу, схему или метаданные файлов.
+Для каждого формата нужен отдельный файл. Команда отклонит путь, который перезапишет конфигурацию, базу, схему, учётные записи auth или метаданные файлов.
 
 ## Схема моделей
 
@@ -136,7 +140,7 @@ export default {
 
 При явной схеме неизвестные поля и коллекции запрещены. Исключение — хранимые ключи, выведенные из связей. Исходная база проверяется при загрузке. Генерация использует описание моделей.
 
-REST без схемы создаёт ключ `id` и сохраняет произвольные JSON-поля. Для фильтров и выбора отдельных полей используются имена в формате идентификаторов; остальные поля возвращаются через `scope={"*":true}`. Поля с разными типами значений можно читать, но для их использования в `where`, `order` или `nested` нужна явная схема.
+REST без схемы создаёт ключ `id` и сохраняет произвольные JSON-поля. Для фильтров и выбора отдельных полей используются имена в формате идентификаторов; остальные поля возвращаются через `scope=[{"*":true}]`. Поля с разными типами значений можно читать, но фильтрация, сортировка и пагинация неоднородных списков требуют явной схемы.
 
 ### Поля
 
@@ -288,51 +292,59 @@ mutation {
 
 ### Параметры REST-запросов
 
-Параметры `where`, `order`, `pager`, `nested` и `scope` содержат JSON. Пример до URL-кодирования:
+REST принимает один query-параметр `scope` с JSON-массивом `[поля, аргументы?]`. Первый объект выбирает поля, второй задаёт `where`, `order` и `pager` для списка. Этот формат одинаков для корневого запроса, вложенных объектов и связей.
 
-```text
-GET /users?where={"fullName":{"contains":"Мира"}}&order=[{"field":"fullName","direction":"ASC"}]&pager={"page":1,"pageSize":20}
-```
-
-Кодирование через `URLSearchParams`:
+Пример выбора пользователей и их фильмов с отдельной сортировкой и пагинацией:
 
 ```js
-const params = new URLSearchParams({
-  scope: JSON.stringify({ id: true, fullName: true, movies: { id: true, title: true } }),
-  nested: JSON.stringify({ movies: { order: [{ field: 'title', direction: 'ASC' }], pager: { page: 1, pageSize: 5 } } }),
-});
+const scope = [
+  {
+    id: true,
+    fullName: true,
+    movies: [
+      { id: true, title: true },
+      {
+        order: [{ field: 'title', direction: 'ASC' }],
+        pager: { page: 1, pageSize: 5 },
+      },
+    ],
+  },
+  {
+    where: { fullName: { contains: 'Мира' } },
+    order: [{ field: 'fullName', direction: 'ASC' }],
+    pager: { page: 1, pageSize: 20 },
+  },
+];
+const params = new URLSearchParams({ scope: JSON.stringify(scope) });
 const response = await fetch(`/users?${params}`);
 ```
 
-`scope` выбирает поля ответа:
+Обычные поля выбираются через `true`, объекты и связи — через свой массив `scope`. Если аргументы не нужны, в массиве остаётся только объект полей. `"*": true` включает собственные поля и хранимые ключи, кроме `writeOnly`; связи выбираются явно.
+
+Например, собственные поля фильма, пользователи актёров и отсортированные жанры:
 
 ```json
-{
-  "*": true,
-  "actors": {
-    "user": { "id": true, "fullName": true },
-    "genres": { "*": true }
+[
+  {
+    "*": true,
+    "actors": [
+      {
+        "user": [{ "id": true, "fullName": true }],
+        "genres": [
+          { "*": true },
+          { "order": [{ "field": "name", "direction": "ASC" }] }
+        ]
+      }
+    ]
   }
-}
+]
 ```
 
-`true` включает поле, вложенный объект выбирает поля внутри объекта или связи. `"*": true` включает собственные поля и хранимые ключи, кроме `writeOnly`. Связи перечисляются явно. Если указать для связи `true`, вернутся её собственные поля.
+Без `scope` возвращаются собственные поля, как при `[{"*":true}]`. Пустой выбор `[{}]` возвращает объект без полей. Списки сохраняют структуру `{ data, total }`.
 
-Без `scope` выбираются собственные поля. `{}` не выбирает ни одного поля. Значениями могут быть `true` или вложенные объекты; `false`, `null` и массивы возвращают `400`. Списки сохраняют структуру ответа `{ data, total }`.
+Аргументы доступны только у списков. В запросе отдельной записи и в ответе мутации их можно задать для вложенных списков. Параметры проверяются даже на пустых данных; ошибка в выборе ответа отменяет изменения записи. Некорректный `scope` возвращает `400`. Максимальная длина JSON — 10 000 символов, глубина выбора — 32 уровня.
 
-`nested` сопоставляет полные пути ответа и настройки списков:
-
-```json
-{
-  "actors": { "pager": { "pageSize": 5 } },
-  "actors.genres": {
-    "where": { "id": { "in": ["2", "3"] } },
-    "order": [{ "field": "name", "direction": "ASC" }]
-  }
-}
-```
-
-Путь в `nested` должен быть выбран через `scope` и вести к списку объектов. Маршруты отдельных записей и мутации принимают `scope` и `nested`; корневые `where`, `order` и `pager` применяются к GET коллекции. Неизвестные имена и небезопасные пути возвращают `400`.
+OpenAPI остаётся версии 3.0.3. В этой версии нельзя задать отдельную схему для каждой позиции массива: назначение элементов описано в документации, а их порядок строго проверяет сервер.
 
 ### GraphQL
 
@@ -526,10 +538,48 @@ Content-Type: application/json
 
 При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Метаданные содержат `directory`, `mimeType` и `name`; размер сервер читает из файла, а URL формирует сам. Директории и файл метаданных создаются по мере необходимости.
 
-Используйте один процесс сервера для дисковой базы и файлового хранилища. Перед ручным изменением файлов или метаданных остановите его. Пути в хранилище не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, счётчики, схему, загруженную конфигурацию или файл метаданных.
+Используйте один процесс сервера для дисковой базы и файлового хранилища. Перед ручным изменением файлов или метаданных остановите его. Пути в хранилище не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, счётчики, схему, учётные записи auth, загруженную конфигурацию или файл метаданных.
 
 Отправляйте файл как бинарное тело запроса. В браузере для этого можно использовать `xhr.send(file)`, а прогресс отслеживать через `XMLHttpRequest.upload.onprogress`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 
+## Аутентификация
+
+Модуль auth добавляет REST-маршруты входа, получения текущего пользователя и выхода. **Он не ограничивает доступ к REST-записям, файлам и GraphQL.**
+
+Создайте учётную запись в отдельном файле с помощью `setup-auth.mjs`:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { hashPassword } from '@kollors/deep-json-server/auth';
+
+const password = process.env.DJS_PASSWORD;
+if (!password) throw new Error('Set DJS_PASSWORD');
+await writeFile('./auth.json', JSON.stringify([
+  { id: '1', username: 'admin', passwordHash: await hashPassword(password) },
+], null, 2), { flag: 'wx', mode: 0o600 });
+```
+
+Задайте `DJS_PASSWORD` и выполните `node setup-auth.mjs`. Добавьте файл в конфигурацию сервера:
+
+```js
+export default {
+  database: { path: './database.json' },
+  auth: { users: './auth.json', expiresIn: 3600 },
+};
+```
+
+Запустите `npx deep-json-server --auth server.config.js` или задайте `auth.enabled: true`. Каждой записи нужны уникальный строковый `id`, уникальный `username` и `passwordHash`, созданный функцией выше. Пароли хешируются через scrypt со случайной солью. Файл читается при запуске; после его изменения перезапустите сервер.
+
+| REST-запрос | Входные данные | Ответ |
+|---|---|---|
+| `POST /auth/login` | JSON `{ "username": "admin", "password": "…" }` | `{ accessToken, expiresIn, user: { id, username } }` |
+| `GET /auth/me` | Bearer-токен | `{ id, username }` |
+| `POST /auth/logout` | Bearer-токен | `{ success: true }` |
+
+Передавайте токен в заголовке `Authorization: Bearer <accessToken>`. Неверные учётные данные, недействительный или истёкший токен возвращают HTTP 401. Сессии хранятся в памяти и исчезают при перезапуске; выход отзывает переданный токен. Вход может вернуть HTTP 429 при слишком большом числе одновременных попыток или активных сессий.
+
+В OpenAPI добавляются эти REST-операции и Bearer-схема для `/auth/me` и `/auth/logout`. В Swagger UI токен из ответа на вход можно вставить в **Authorize**. Для экспорта схем включите auth в конфигурации или используйте `generate openapi --auth server.config.js`; файл учётных записей при генерации не читается. Для GraphQL и OpenAPI по-прежнему нужна `database.schema`.
+
 ## Программный API
 
 ```js
@@ -542,7 +592,7 @@ await server.listen();
 // await server.close();
 ```
 
-Методы `openapi()` и `graphql()` возвращают схемы и требуют `database.schema`. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск. Возможности сервера можно переопределить через `createServer(config, { files: false, graphql: true, openapi: true })`.
+Методы `openapi()` и `graphql()` возвращают схемы и требуют `database.schema`. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск. Возможности сервера можно переопределить через `createServer(config, { files: false, graphql: true, openapi: true, auth: true })`.
 
 Эти функции доступны и через общий импорт `@kollors/deep-json-server`. Адаптеры сервера загружаются при включении. Генераторы можно использовать отдельно:
 
@@ -556,13 +606,15 @@ await writeOpenapi(document, './generated/openapi.yaml');
 await writeGraphql(sdl, './generated/schema.graphql');
 ```
 
+`generateOpenapi()` принимает `{ auth: true }`, чтобы добавить операции auth. Функция `hashPassword()` доступна и через общий импорт пакета.
+
 `generateOpenapi()` также принимает `host`, `port`, `pageSize`, `maxPageSize` и `info`. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели. Размеры страниц должны быть положительными целыми числами; `pageSize` не может превышать `maxPageSize`.
 
 ## Хранение и разработка
 
 Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один процесс сервера. Счётчики `increment` хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера.
 
-Сервер предназначен для имитации API. Авторизацию и хеширование паролей при необходимости реализуйте в приложении.
+Сервер предназначен для имитации API. Правила доступа к данным задаются в вашем приложении.
 
 ```sh
 npm ci

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export type { AuthConfig, AuthSession, AuthUser, AuthUserRecord } from './src/auth/contract.js';
+export { hashPassword } from './src/auth/public.js';
 export type { DatabaseConfig, DeepJsonServerConfig, FilesConfig, GraphqlConfig, MemoryFile, OpenapiConfig, ServerConfig } from './src/config.js';
 export type { ServerFeatures } from './src/features.js';
 export type { FileUpdate } from './src/files/contract.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { hashPassword } from './src/auth/public.js';
 export { generateGraphql, generateOpenapi, writeGraphql, writeOpenapi } from './src/schema.js';
 export { createServer } from './src/server.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOpD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/src/auth/contract.d.ts

@@ -0,0 +1,26 @@
+export interface AuthUser {
+    id: string;
+    username: string;
+}
+export interface AuthUserRecord extends AuthUser {
+    passwordHash: string;
+}
+export interface AuthConfig {
+    enabled?: boolean;
+    users: string | AuthUserRecord[];
+    /** Session lifetime in seconds. Defaults to one hour. */
+    expiresIn?: number;
+}
+export interface AuthSession {
+    accessToken: string;
+    expiresIn: number;
+    user: AuthUser;
+}
+export declare const AUTH_PATHS: {
+    readonly login: '/auth/login';
+    readonly me: '/auth/me';
+    readonly logout: '/auth/logout';
+};
+export declare const DEFAULT_SESSION_SECONDS = 3600;
+export declare const MAX_USERNAME_LENGTH = 256;
+export declare const MAX_PASSWORD_LENGTH = 1024;

package/dist/src/auth/contract.js

@@ -0,0 +1,5 @@
+export const AUTH_PATHS = { login: '/auth/login', me: '/auth/me', logout: '/auth/logout' };
+export const DEFAULT_SESSION_SECONDS = 3600;
+export const MAX_USERNAME_LENGTH = 256;
+export const MAX_PASSWORD_LENGTH = 1024;
+//# sourceMappingURL=contract.js.map

package/dist/src/auth/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/auth/contract.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAW,CAAC;AACpG,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC"}

package/dist/src/auth/openapi.d.ts

@@ -0,0 +1,10 @@
+import type { OpenapiDocument, OpenapiSchema } from '../types.js';
+export declare const AUTH_SCHEMAS: Record<string, OpenapiSchema>;
+export declare const AUTH_SECURITY_SCHEMES: {
+    AuthBearer: {
+        type: string;
+        scheme: string;
+        description: string;
+    };
+};
+export declare function authOpenapiPaths(): OpenapiDocument['paths'];

package/dist/src/auth/openapi.js

@@ -0,0 +1,62 @@
+import { json, ref, response } from '../openapi/helpers.js';
+import { AUTH_PATHS, MAX_PASSWORD_LENGTH, MAX_USERNAME_LENGTH } from './contract.js';
+export const AUTH_SCHEMAS = {
+    AuthUser: { type: 'object', additionalProperties: false, required: ['id', 'username'], properties: { id: { type: 'string' }, username: { type: 'string' } } },
+    AuthLoginInput: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['username', 'password'],
+        properties: {
+            username: { type: 'string', minLength: 1, maxLength: MAX_USERNAME_LENGTH },
+            password: { type: 'string', format: 'password', writeOnly: true, minLength: 1, maxLength: MAX_PASSWORD_LENGTH },
+        },
+    },
+    AuthSession: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accessToken', 'expiresIn', 'user'],
+        properties: {
+            accessToken: { type: 'string' },
+            expiresIn: { type: 'integer', minimum: 1 },
+            user: ref('AuthUser'),
+        },
+    },
+    AuthLogoutResult: { type: 'object', additionalProperties: false, required: ['success'], properties: { success: { type: 'boolean' } } },
+};
+export const AUTH_SECURITY_SCHEMES = { AuthBearer: { type: 'http', scheme: 'bearer', description: 'Session token returned by POST /auth/login. Used only by GET /auth/me and POST /auth/logout.' } };
+export function authOpenapiPaths() {
+    const unauthorized = response('Invalid credentials or expired session', ref('Error'));
+    return {
+        [AUTH_PATHS.login]: {
+            post: {
+                operationId: 'authLogin',
+                tags: ['auth'],
+                security: [],
+                requestBody: { required: true, ...json(ref('AuthLoginInput')) },
+                responses: {
+                    200: response('Session created', ref('AuthSession')),
+                    400: response('Invalid input', ref('Error')),
+                    401: unauthorized,
+                    429: response('Too many login attempts or sessions', ref('Error')),
+                },
+            },
+        },
+        [AUTH_PATHS.me]: {
+            get: {
+                operationId: 'authMe',
+                tags: ['auth'],
+                security: [{ AuthBearer: [] }],
+                responses: { 200: response('Current auth user', ref('AuthUser')), 401: unauthorized },
+            },
+        },
+        [AUTH_PATHS.logout]: {
+            post: {
+                operationId: 'authLogout',
+                tags: ['auth'],
+                security: [{ AuthBearer: [] }],
+                responses: { 200: response('Session revoked', ref('AuthLogoutResult')), 401: unauthorized },
+            },
+        },
+    };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/src/auth/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../src/auth/openapi.ts"],"names":[],"mappings":"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"}

package/dist/src/auth/password.d.ts

@@ -0,0 +1,4 @@
+export declare const validPasswordHash: (value: unknown) => value is string;
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+export declare const DUMMY_HASH: string;

package/dist/src/auth/password.js

@@ -0,0 +1,25 @@
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
+import { MAX_PASSWORD_LENGTH } from './contract.js';
+// OWASP scrypt profile: N=2^14, r=8, p=5 (16 MiB memory).
+const PREFIX = 'scrypt$16384$8$5';
+const HASH_PATTERN = /^scrypt\$16384\$8\$5\$([0-9a-f]{32})\$([0-9a-f]{64})$/;
+export const validPasswordHash = (value) => typeof value === 'string' && HASH_PATTERN.test(value);
+const derive = (password, salt) => new Promise((resolve, reject) => {
+    scrypt(password, salt, 32, { N: 16384, r: 8, p: 5 }, (error, key) => (error ? reject(error) : resolve(key)));
+});
+export async function hashPassword(password) {
+    if (typeof password !== 'string' || !password.length || password.length > MAX_PASSWORD_LENGTH)
+        throw new Error(`Password must contain 1..${MAX_PASSWORD_LENGTH} characters`);
+    const salt = randomBytes(16);
+    const hash = await derive(password, salt);
+    return `${PREFIX}$${salt.toString('hex')}$${hash.toString('hex')}`;
+}
+export async function verifyPassword(password, encoded) {
+    const parts = HASH_PATTERN.exec(encoded);
+    if (!parts)
+        return false;
+    const actual = await derive(password, Buffer.from(parts[1], 'hex'));
+    return timingSafeEqual(actual, Buffer.from(parts[2], 'hex'));
+}
+export const DUMMY_HASH = `${PREFIX}$${'0'.repeat(32)}$${'0'.repeat(64)}`;
+//# sourceMappingURL=password.js.map

package/dist/src/auth/password.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password.js","sourceRoot":"","sources":["../../../src/auth/password.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,MAAM,GAAG,kBAAkB,CAAC;AAClC,MAAM,YAAY,GAAG,uDAAuD,CAAC;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAc,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5H,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAE,IAAY,EAAmB,EAAE,CACjE,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAC9B,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC/G,CAAC,CAAC,CAAC;AACL,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,mBAAmB;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,mBAAmB,aAAa,CAAC,CAAC;IAC7K,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC1C,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACrE,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB,EAAE,OAAe;IACpE,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACpE,OAAO,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAC/D,CAAC;AACD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC"}