Безпека та автентифікація

Безпека та автентифікація

PgArachne повністю покладається на систему прав доступу PostgreSQL. Він не винаходить власні списки контролю доступу (ACL). PgArachne підтримує чотири методи автентифікації. Методи 1–3 використовують SET LOCAL ROLE для перемикання ідентичності; метод 4 (прямі облікові дані) підключається безпосередньо як користувач, тож перемикання ролі не потрібне.

Це стосується endpoint’ів JSON-RPC та MCP. SSE endpoint є єдиним винятком — він автентифікує того, хто звертається, але не перемикає роль і не перевіряє права на рівні каналу, оскільки канали LISTEN/NOTIFY PostgreSQL не є об’єктами бази даних із власними GRANT, які можна було б застосувати. Що це означає на практиці, дивіться на сторінці SSE.

1. Інтерактивний вхід (JWT)

Користувачі автентифікуються за допомогою свого справжнього імені користувача та пароля PostgreSQL через автентифікацію HTTP Basic на POST /{prefix}/{database}/token. У разі успіху вони отримують короткостроковий JWT. Наступні запити передають цей токен у заголовку Authorization: Bearer <token>, і PgArachne перемикає активну роль на цього користувача на час виконання кожного запиту.

curl -X POST http://localhost:8080/db/my_database/token -u demo_user:user_password
→ {"token":"eyJhbGciOi...","token_type":"Bearer","expires_in":28800}

Облікові дані передаються в заголовку Authorization, ніколи в тілі JSON, а вхід має власну URL-адресу, тож зворотний проксі може обмежувати його частоту, не читаючи тіла запитів. Відповідь ніколи не кешується.

Потребує JWT_SECRET. Якщо його не налаштовано, endpoint повертає HTTP 404 (-32601), а клієнти натомість використовують прямі облікові дані (метод 4) або API-токени (метод 2).

2. Сервісні облікові записи (API-токени)

Для автоматизованих систем або скриптів рекомендується використовувати довгострокові API-токени.

• Токени зберігаються в таблиці pgarachne.api_tokens.
• Кожен токен зіставлений із конкретною роллю бази даних.
• Надсилайте токен через заголовок Authorization: Bearer <token>.

Створення API-токенів вимагає pgarachne_admin. Використовуйте pgarachne.add_api_token(...) з роллю, яка є учасником pgarachne_admin.

3. Зовнішній постачальник ідентичності (власний JWT)

Якщо користувачі автентифікуються поза PgArachne (наприклад, через зовнішній сервіс автентифікації), ви можете видавати JWT там і надсилати їх безпосередньо до PgArachne.

• Формат заголовка: Authorization: Bearer <jwt>.
• Підписування: лише HMAC (HS256 / HS384 / HS512) із тим самим JWT_SECRET, який налаштовано в PgArachne.
• Обов’язкові claim-и: db_role (рядок, не порожній) та db_name (рядок, має відповідати сегменту шляху :database).
• Обов’язковий claim: exp (Unix-часова метка) для терміну дії токена.

Потребує JWT_SECRET; без нього значення Bearer перевіряються лише як API-токени.

Приклад мінімального payload:

{
  "db_role": "demo_user",
  "db_name": "my_database",
  "exp": 1767225600
}

Примітка: асиметричні алгоритми JWT (наприклад, RS256 / ES256) не підтримуються.

4. Прямі облікові дані бази даних (Basic Auth)

Найпростіший варіант: надсилайте ім’я користувача та пароль PostgreSQL з кожним запитом, використовуючи стандартну HTTP Basic Authentication. PgArachne відкриває окремий пул з’єднань, автентифікований безпосередньо як цей користувач — SET LOCAL ROLE при цьому не виконується.

Authorization: Basic <base64(username:password)>

Приклад з curl:

curl -X POST http://localhost:8080/db/my_database/jsonrpc \
  -u demo_user:user_password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"api.hello_world","params":{},"id":1}'

Ключові відмінності від методів на основі токенів:

• GRANT demo_user TO pgarachne не потрібен — PgArachne не перемикає ролі.
• Row-Level Security PostgreSQL та права доступу GRANT застосовуються як зазвичай, оскільки з’єднання виконується від імені фактичного користувача.
• Пули з’єднань підтримуються окремо для кожного користувача для ефективності, з максимальним часом життя 5 хвилин. Після зміни пароля старі з’єднання завершуються протягом цього вікна.
• Щоб ключі ідемпотентності працювали з прямими обліковими даними, надайте користувачеві право EXECUTE ON FUNCTION pgarachne.save_idempotency_key(text, text).

-- Потрібно лише для автентифікації через JWT / API-токен:
GRANT demo_user TO pgarachne;

Порівняння методів автентифікації

Які функції можна викликати

PgArachne не має власного списку дозволених схем — те, що може викликати роль, визначають виключно привілеї PostgreSQL. Функцію можна викликати (і її перелічують capabilities, MCP tools/list та експорт OpenAPI), якщо вона приймає єдиний параметр jsonb, роль має на неї EXECUTE, а також роль має USAGE на її схему. Функції в pg_catalog, information_schema, pgarachne та функції, що належать розширенням, не включаються до переліку для зручності читання, але на них поширюються ті самі привілеї.

-- Нові функції не виконуються всіма (запускайте від імені ролі, яка їх створює):
ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;

-- Тримайте API-функції в окремій схемі та надавайте привілеї явно:
GRANT USAGE ON SCHEMA api TO demo_user;
GRANT EXECUTE ON FUNCTION api.hello_world(jsonb) TO demo_user;

Захист від перебору (brute-force)

LOGIN_RATE_LIMIT та LOGIN_RATE_LIMIT_PER_IP застосовуються до кожного методу автентифікації на кожному endpoint-і (JSON-RPC, MCP, SSE, OpenAPI):

• /token: кожна спроба зараховується до лімітів на (IP, ім’я користувача) та на IP.
• Прямі облікові дані (Basic Auth): невдалі спроби зараховуються до лімітів на (IP, ім’я користувача) та на IP. Успішні запити не враховуються, тож легітимний клієнт, який надсилає облікові дані з кожним запитом, ніколи не буде обмежений.
• Bearer-токени (JWT або API-токен): невдалі спроби зараховуються до ліміту на IP.

Після вичерпання ліміту подальші спроби відхиляються з HTTP 429, доки не мине вікно (LOGIN_RATE_WINDOW) — облікові дані при цьому взагалі не перевіряються.