Payment Orchestrator

Тема

05.05 Audit Logs ​

Статус: черновик для обсуждения

1. Назначение документа ​

Этот документ описывает audit log requirements для Back Office и domain entities.

Audit logs нужны, чтобы понимать:

  • кто изменил данные;
  • что именно изменилось;
  • когда это произошло;
  • к какой entity относится изменение;
  • какие old/new values были у измененных non-secret fields;
  • почему система или user пришли к текущему состоянию configuration.

Audit log является обязательным элементом MVP.

2. Где доступен audit log ​

Audit log должен быть доступен:

  • в Platform section как global audit log;
  • в Merchant section как merchant-scoped audit log;
  • на странице каждой сущности как вкладка Audit Logs.

3. Global audit log ​

Global audit log в Platform section нужен для platform users.

Platform user с permission может видеть audit logs по всей системе или по доступному scope.

Global audit log должен поддерживать filters:

  • date/time;
  • actor;
  • entity type;
  • entity ID;
  • action type;
  • merchant / merchant group / brand context, если он выводится из entity;
  • source;
  • changed field;
  • search by text/ID.

4. Merchant-scoped audit log ​

Merchant section должен иметь audit log, который показывает только события по доступным merchant context.

Merchant user с permission видит audit logs только по:

  • merchants, к которым у него есть доступ;
  • merchant groups, к которым у него есть доступ;
  • entities, которые он имеет право видеть;
  • fields, которые доступны по visibility rules и не являются secret values.

Merchant user не должен видеть audit events, которые раскрывают hidden provider/internal information.

5. Audit Logs tab on entity pages ​

На странице каждой сущности должна быть вкладка:

text
Audit Logs

Это относится к сущностям:

  • Merchant;
  • Merchant Group;
  • Brand;
  • User;
  • Role;
  • API Key;
  • Payment Method / MID;
  • MASTER MID;
  • SUB MID;
  • SUB MID Aggregator;
  • Routing Rule;
  • Velocity Rule;
  • FX / Fee configuration;
  • Transaction;
  • Webhook;
  • System Settings, если такая page появится после MVP.

Entity audit tab показывает audit events только по этой entity и связанным changes.

6. Какие действия логируем ​

Audit log пишется на:

  • create;
  • update;
  • delete;
  • status change;
  • access change;
  • role assignment;
  • role removal;
  • permission change;
  • user merchant access added;
  • user merchant access removed;
  • user merchant role changed;
  • user merchant group access added;
  • user merchant group access removed;
  • automatic user access recalculated after merchant group membership change;
  • API key creation;
  • API key rotation;
  • API key revoke;
  • routing configuration change;
  • velocity configuration change;
  • FX / fee configuration change;
  • transaction correction;
  • manual webhook resend;
  • session termination by platform admin;
  • invite created / resent / accepted / expired;
  • invite rejected because email already exists;
  • password reset completed;
  • 2FA setup completed.

7. View actions ​

Обычные view actions не нужно писать в audit log.

Например, не нужно логировать:

  • user opened transaction details;
  • user opened provider raw data;
  • user opened merchant page;
  • user opened audit log tab.

Если в будущем появится compliance requirement логировать просмотр sensitive data, это должно быть описано отдельно.

8. Auth/session events ​

Auth/session events тоже должны логироваться.

Они могут храниться:

  • в общем audit log;
  • или в отдельном security log.

Для MVP продуктово важно, чтобы platform users с permission могли расследовать auth/session events.

Минимально логируем:

  • login success;
  • login failed;
  • logout, если технически фиксируется;
  • session created;
  • session terminated by owner;
  • session terminated by platform admin;
  • password reset requested;
  • password reset completed;
  • 2FA setup completed;
  • 2FA failed;
  • invite events;
  • user access changes;
  • role/permission changes.

Точная физическая модель audit log vs security log может быть определена development team.

9. Audit event structure ​

Каждый audit event должен содержать:

  • event ID;
  • timestamp;
  • actor user ID;
  • actor user email;
  • actor user type;
  • actor IP, если доступно;
  • actor user agent, если доступно;
  • source;
  • action type;
  • entity type;
  • entity ID;
  • entity display name, если доступно;
  • context type;
  • changed fields;
  • old values for changed non-secret fields;
  • new values for changed non-secret fields;
  • reason/comment, если был указан;
  • request ID / correlation ID, если доступно.

merchantId, brandId и merchantGroupId не являются обязательными базовыми fields audit event.

Context должен определяться через:

  • entity type;
  • entity ID;
  • связи самой entity.

Причина: не все сущности находятся внутри merchant / brand / merchant group context. Например, user или platform role могут не относиться к конкретному merchant.

Если development team решит денормализовать context fields для быстрого поиска, это техническая оптимизация, а не product requirement.

request ID / correlation ID - это технический identifier для связи audit event с API request, logs, traces и другими system events.

Actor IP and user agent should be stored for Back Office user actions and login/security events.

Product owner не должен задавать его формат. Development team должна выбрать naming и propagation approach.

10. Old value / new value ​

Audit log должен хранить old value и new value для измененных non-secret fields.

Это нужно для:

  • investigation;
  • rollback planning;
  • support;
  • understanding configuration changes;
  • accountability.

Secret values не должны сохраняться в audit log ни в открытом, ни в masked виде.

Для secret field audit event должен показывать только факт изменения field.

Пример:

text
changedFields: ["providerSecretKey"]
oldValues: {}
newValues: {}
message: "Secret field was updated"

Обычные non-secret fields должны сохранять old/new values.

11. Secret values ​

Secret values не должны храниться в audit log.

Нельзя сохранять ни actual value, ни masked copy, ни encrypted copy в audit log для:

  • API key secret;
  • provider credentials;
  • provider secret keys;
  • passwords;
  • 2FA secrets;
  • reset codes;
  • invite tokens;
  • session tokens;
  • webhook signing secrets, если такие появятся;
  • любые private keys / tokens.

Audit log может показывать безопасный факт изменения:

text
providerSecretKey: updated

Для non-secret sensitive fields, например email или IP, visibility/masking rules могут применяться отдельно в зависимости от permissions и UI context.

12. Visibility and secrecy ​

Audit log visibility зависит от:

  • user type;
  • permissions;
  • merchant access;
  • merchant group access;
  • entity visibility rules;
  • secret data rules.

Platform user с permission может видеть все audit logs в рамках своего access scope.

Merchant user с permission видит только merchant-safe audit logs.

Если audit event относится к platform-hidden SUB MID / SUB MID AGGREGATOR / provider configuration, merchant user не должен видеть скрытые детали.

13. Immutability ​

Audit log immutable.

Audit events нельзя:

  • редактировать из UI;
  • удалять из UI;
  • переписывать обычным user action.

Если нужно исправить ошибочную информацию, создается новый audit event / correction event.

14. Export ​

Audit logs можно экспортировать только users с соответствующей permission.

Export должен учитывать:

  • permissions;
  • visibility rules;
  • secret data rules;
  • merchant / merchant group access.

Secret values не должны попадать в export.

14.1 Retention ​

Audit/security logs должны храниться indefinitely.

Product requirement:

text
Audit/security events are retained indefinitely / always.

Если future legal/security/compliance constraints require different retention, security/legal team должна предложить отдельное решение.

15. Acceptance Criteria ​

Audit Logs считаются согласованными для MVP, если:

  • Audit log доступен в Platform section.
  • Audit log доступен в Merchant section.
  • На странице каждой сущности есть вкладка Audit Logs.
  • Audit log пишется на create/update/delete/status changes/access changes.
  • Audit log не пишется на обычные view actions.
  • Auth/session events логируются в audit/security log.
  • User access changes логируются отдельными audit events.
  • Merchant user видит audit logs только по доступным merchants/entities.
  • Platform user с permission видит audit logs в рамках своего scope.
  • Audit log хранит old/new values для non-secret fields.
  • Secret values не сохраняются в audit log.
  • Merchant/brand/merchant group context выводится из entity, а не является обязательным base field.
  • request ID / correlation ID является техническим identifier для связи audit/logs/traces.
  • Actor IP/user agent сохраняются для Back Office actions и login/security events, если доступны.
  • Audit log immutable.
  • Audit events нельзя редактировать/удалять из UI.
  • Audit export учитывает permissions, visibility и secret data rules.
  • Audit export входит в MVP.
  • Audit/security logs хранятся indefinitely.

16. Open Questions ​

Product open questions отсутствуют.

Technical/design follow-up:

  1. Решить, будет ли auth/session log физически частью audit log или отдельным security log.
  2. Определить exact list of entity types for MVP.
  3. Определить exact naming для requestId, correlationId или traceId.
  4. Определить storage/indexing approach для поиска по audit logs.