From 301afec2c4a0d559e2601c1ebdf275ff11c523c8 Mon Sep 17 00:00:00 2001 From: AliJohari05 Date: Fri, 6 Nov 2026 19:33:09 +0330 Subject: [PATCH 1/6] The issue with the appearance of the admin panel in the development environment has been resolved. --- s4_rsk/config/urls.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/s4_rsk/config/urls.py b/s4_rsk/config/urls.py index 52c8a0b..d8104e6 100644 --- a/s4_rsk/config/urls.py +++ b/s4_rsk/config/urls.py @@ -1,4 +1,6 @@ +from django.conf import settings from django.contrib import admin +from django.contrib.staticfiles.urls import staticfiles_urlpatterns from django.urls import include, path from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView @@ -17,3 +19,7 @@ path("api/v1/", include("rules.urls")), path("api/v1/", include("reviews.urls")), ] + +# Gunicorn does not serve Django's development static files itself. +if settings.DEBUG: + urlpatterns += staticfiles_urlpatterns() From 0c5606c3b80855d7c27df3c4b542376aa0093711 Mon Sep 17 00:00:00 2001 From: AliJohari05 Date: Fri, 6 Nov 2026 20:20:55 +0330 Subject: [PATCH 2/6] feat: authenticate risk APIs with JWT --- README.md | 18 +- contracts/bruno/README.md | 11 +- contracts/bruno/Rules-anonymous.bru | 2 +- contracts/bruno/Rules-manager.bru | 2 +- contracts/bruno/Rules-non-manager.bru | 2 +- contracts/openapi.yaml | 332 +++++++++++++++++++++++++- contracts/s3-s4-jwt-draft.md | 9 + docs/adr/ADR-001-authentication.md | 3 +- docs/reports/jwt-authentication.md | 23 ++ docs/us-02a-risk-rules.md | 11 +- frontend/src/api/schema.d.ts | 143 ++++++++++- openapi/s4_rsk.yaml | 104 +++++--- requirements.txt | 3 +- s4_rsk/.env.example | 1 + s4_rsk/assessments/tests.py | 5 +- s4_rsk/assessments/views.py | 6 + s4_rsk/common/auth_views.py | 18 ++ s4_rsk/common/permissions.py | 13 +- s4_rsk/common/test_jwt_auth.py | 74 ++++++ s4_rsk/config/settings.py | 22 +- s4_rsk/config/urls.py | 4 + s4_rsk/rules/tests.py | 20 +- 22 files changed, 742 insertions(+), 84 deletions(-) create mode 100644 contracts/s3-s4-jwt-draft.md create mode 100644 docs/reports/jwt-authentication.md create mode 100644 s4_rsk/common/auth_views.py create mode 100644 s4_rsk/common/test_jwt_auth.py diff --git a/README.md b/README.md index f4556ef..4a508a7 100644 --- a/README.md +++ b/README.md @@ -59,18 +59,12 @@ the database. `/ready` queries PostgreSQL and returns ## Authentication baseline -Management endpoints use Django sessions. Unsafe authenticated requests must -include the CSRF cookie and `X-CSRFToken`. The `manager`, `operator` and -`analyst` roles are Django groups; the initial rule list requires `manager`. -The staff flag grants no API role by itself. See -[ADR-001](docs/adr/ADR-001-authentication.md) for the exact 403 problem codes, -same-origin UI contract and pending S3 authentication decision. - -For local Swagger use, create an interactive account with -`python s4_rsk/manage.py createsuperuser`, log into `/admin/login/`, create the -`manager` group and explicitly assign it to that account. Do not store real -passwords in fixtures or request collections. Production requires `DEBUG=False`, -a non-development `SECRET_KEY`, HTTPS, correct `ALLOWED_HOSTS` and secure cookies. +API endpoints use Bearer JWT; Django admin retains session authentication. +The risk-rule list requires group `manager`, while assessment endpoints require +the separate `payment_service` group. See [JWT instructions](docs/reports/jwt-authentication.md) +and the [draft S3 contract](contracts/s3-s4-jwt-draft.md). Production requires +HTTPS, a strong `SECRET_KEY`, a distinct `JWT_SIGNING_KEY`, shared rate-limiting, +secure deployment settings, and agreement with S3 on service identity. ## Tests and schema validation diff --git a/contracts/bruno/README.md b/contracts/bruno/README.md index 569f6f2..bcbd5f8 100644 --- a/contracts/bruno/README.md +++ b/contracts/bruno/README.md @@ -1,15 +1,14 @@ # Manual acceptance requests Open this folder as a Bruno collection, select Local, and set local secret -variables `managerSessionId` and `nonManagerSessionId` from your own development -accounts. Never save actual cookie values in tracked files. Seed the development +variables `managerAccessToken` and `nonManagerAccessToken` from your own development +accounts using the JWT guide. Never save actual token values in tracked files. Seed the development rules explicitly using the steps in `docs/us-02a-risk-rules.md`. -Disable automatic cookie-jar sending for the anonymous request; otherwise a -previous manager cookie could authenticate it. The non-manager account must be -logged in but must not belong to manager. Run success and forbidden requests +The anonymous request sends no bearer token. The non-manager account must not +belong to manager. Run success and forbidden requests independently and retain actual results/screenshots as review evidence. These files are request definitions; their presence alone is not evidence of -a completed manual Bruno run. Equivalent session/permission paths are covered +a completed manual Bruno run. JWT and permission paths are covered by the automated PostgreSQL integration suite. diff --git a/contracts/bruno/Rules-anonymous.bru b/contracts/bruno/Rules-anonymous.bru index 1c6510e..a717fb8 100644 --- a/contracts/bruno/Rules-anonymous.bru +++ b/contracts/bruno/Rules-anonymous.bru @@ -12,7 +12,7 @@ get { tests { test("Anonymous session is rejected", function () { - expect(res.getStatus()).to.equal(403); + expect(res.getStatus()).to.equal(401); expect(res.getBody().code).to.equal("UNAUTHORIZED"); }); } diff --git a/contracts/bruno/Rules-manager.bru b/contracts/bruno/Rules-manager.bru index 502f4c5..31dbea0 100644 --- a/contracts/bruno/Rules-manager.bru +++ b/contracts/bruno/Rules-manager.bru @@ -11,7 +11,7 @@ get { } headers { - Cookie: sessionid={{managerSessionId}} + Authorization: Bearer {{managerAccessToken}} } tests { diff --git a/contracts/bruno/Rules-non-manager.bru b/contracts/bruno/Rules-non-manager.bru index 23f6bcd..5004832 100644 --- a/contracts/bruno/Rules-non-manager.bru +++ b/contracts/bruno/Rules-non-manager.bru @@ -11,7 +11,7 @@ get { } headers { - Cookie: sessionid={{nonManagerSessionId}} + Authorization: Bearer {{nonManagerAccessToken}} } tests { diff --git a/contracts/openapi.yaml b/contracts/openapi.yaml index 0559088..4e84e14 100644 --- a/contracts/openapi.yaml +++ b/contracts/openapi.yaml @@ -5,6 +5,151 @@ info: description: Real-time transaction risk evaluation, dynamic rule engine, blocklist, and manual review service. paths: + /api/v1/auth/token/: + post: + operationId: api_v1_auth_token_create + description: |- + Takes a set of user credentials and returns an access and refresh JSON web + token pair to prove the authentication of those credentials. + tags: + - api + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TokenObtainPair' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TokenObtainPair' + description: '' + /api/v1/auth/token/logout/: + post: + operationId: api_v1_auth_token_logout_create + description: |- + Takes a token and blacklists it. Must be used with the + `rest_framework_simplejwt.token_blacklist` app installed. + tags: + - api + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TokenBlacklist' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TokenBlacklist' + description: '' + /api/v1/auth/token/refresh/: + post: + operationId: api_v1_auth_token_refresh_create + description: |- + Takes a refresh type JSON web token and returns an access type JSON web + token if the refresh token is valid. + tags: + - api + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TokenRefresh' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TokenRefresh' + description: '' + /api/v1/risk-assessments: + post: + operationId: createRiskAssessment + description: |- + POST /api/v1/risk-assessments + Evaluates a payment transaction and persists the initial risk decision (US-01A). + summary: Evaluate transaction risk and persist decision + parameters: + - in: header + name: Idempotency-Key + schema: + type: string + format: uuid + description: Unique key to guarantee idempotent assessment creation. + - in: header + name: X-Correlation-ID + schema: + type: string + description: Distributed tracing correlation identifier. + tags: + - Risk Assessments + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RiskAssessmentRequest' + required: true + security: + - jwtAuth: [] + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/RiskAssessmentResponse' + description: '' + '400': + content: + application/json: + schema: + type: object + additionalProperties: {} + description: '' + '409': + content: + application/json: + schema: + type: object + additionalProperties: {} + description: '' + /api/v1/risk-assessments/{decision_id}: + get: + operationId: getRiskAssessmentById + description: |- + GET /api/v1/risk-assessments/{decision_id} + Retrieves a previously evaluated risk assessment and its reasons (US-01A). + summary: Retrieve a risk assessment decision by decision_id + parameters: + - in: path + name: decision_id + schema: + type: string + format: uuid + required: true + tags: + - Risk Assessments + security: + - jwtAuth: [] + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/RiskAssessmentDetailResponse' + description: '' + '404': + content: + application/json: + schema: + type: object + additionalProperties: {} + description: '' /api/v1/risk-rules: get: operationId: risk_rules_list @@ -31,7 +176,7 @@ paths: tags: - api security: - - cookieAuth: [] + - jwtAuth: [] responses: '200': headers: @@ -138,6 +283,40 @@ components: - CONNECTED type: string description: '* `CONNECTED` - CONNECTED' + DecisionEnum: + enum: + - APPROVE + - REJECT + - REVIEW + type: string + description: |- + * `APPROVE` - APPROVE + * `REJECT` - REJECT + * `REVIEW` - REVIEW + DecisionReasonResponse: + type: object + description: Output contract for a single reason item. + properties: + code: + type: string + message: + type: string + rule_id: + type: + - string + - 'null' + format: uuid + rule_revision: + type: + - integer + - 'null' + rule_snapshot: + oneOf: + - {} + - type: 'null' + required: + - code + - message Health: type: object properties: @@ -208,6 +387,110 @@ components: - READY type: string description: '* `READY` - READY' + RiskAssessmentDetailResponse: + type: object + description: |- + Extend output contract for GET /api/v1/risk-assessments/{decision_id} + inluding transaction context and snapshot details. + properties: + decision_id: + type: string + format: uuid + transaction_id: + type: string + format: uuid + decision: + $ref: '#/components/schemas/DecisionEnum' + evaluated_at: + type: string + format: date-time + reasons: + type: array + items: + $ref: '#/components/schemas/DecisionReasonResponse' + amount: + type: integer + currency: + type: string + source_iban: + type: string + destination_iban: + type: string + occurred_at: + type: string + format: date-time + required: + - amount + - currency + - decision + - decision_id + - destination_iban + - evaluated_at + - occurred_at + - reasons + - source_iban + - transaction_id + RiskAssessmentRequest: + type: object + description: Input contract for POST /api/v1/risk-assessments (Section 6). + properties: + transaction_id: + type: string + format: uuid + description: Unique transaction UUID generated by S3-PAY. + amount: + type: integer + description: Transfer amount in IRR (strictly positive int64 integer). + currency: + type: string + description: Must be 'IRR'. + maxLength: 3 + source_iban: + type: string + description: Source Iranian IBAN (IR + 24 ASCII digits). + maxLength: 26 + destination_iban: + type: string + description: Destination Iranian IBAN (IR + 24 ASCII digits). + maxLength: 26 + occurred_at: + type: string + format: date-time + description: ISO-8601 UTC timestamp of the transaction. + required: + - amount + - currency + - destination_iban + - occurred_at + - source_iban + - transaction_id + RiskAssessmentResponse: + type: object + description: |- + Output contract for POST /api/v1/risk-assessments (201 Craeted) + and GET /api/v1/risk-assessments/{decision_id} (200 OK) + properties: + decision_id: + type: string + format: uuid + transaction_id: + type: string + format: uuid + decision: + $ref: '#/components/schemas/DecisionEnum' + evaluated_at: + type: string + format: date-time + reasons: + type: array + items: + $ref: '#/components/schemas/DecisionReasonResponse' + required: + - decision + - decision_id + - evaluated_at + - reasons + - transaction_id RiskRule: type: object properties: @@ -252,6 +535,45 @@ components: - revision - type - updated_at + TokenBlacklist: + type: object + properties: + refresh: + type: string + writeOnly: true + required: + - refresh + TokenObtainPair: + type: object + properties: + username: + type: string + writeOnly: true + password: + type: string + writeOnly: true + access: + type: string + readOnly: true + refresh: + type: string + readOnly: true + required: + - access + - password + - refresh + - username + TokenRefresh: + type: object + properties: + access: + type: string + readOnly: true + refresh: + type: string + required: + - access + - refresh TypeEnum: enum: - AMOUNT_LIMIT @@ -261,7 +583,7 @@ components: * `AMOUNT_LIMIT` - Amount limit * `BLOCKLIST` - Blocklist securitySchemes: - cookieAuth: - type: apiKey - in: cookie - name: sessionid + jwtAuth: + type: http + scheme: bearer + bearerFormat: JWT diff --git a/contracts/s3-s4-jwt-draft.md b/contracts/s3-s4-jwt-draft.md new file mode 100644 index 0000000..7aa6b4e --- /dev/null +++ b/contracts/s3-s4-jwt-draft.md @@ -0,0 +1,9 @@ +# پیش‌نویس قرارداد امنیتی S3-PAY و S4-RSK + +**وضعیت: پیش‌نویس؛ نیازمند تأیید تیم S3 و ناظر فنی.** این سند توافق نهایی، اتصال عملیاتی بین دو سرویس یا پیاده‌سازی issuer خارجی نیست. + +در پیاده‌سازی فعلی S4 فقط توکن صادرشده توسط خود S4 با امضای معتبر، issuer `labbank-s4-rsk` و audience `labbank-s4-rsk-api` پذیرفته می‌شود. حساب اختصاصی و فعال S3 باید عضو گروه `payment_service` باشد تا بتواند POST `/api/v1/risk-assessments` و GET `/api/v1/risk-assessments/{decision_id}` را فراخوانی کند؛ دسترسی فهرست قوانین به گروه `manager` محدود است. توکن انسان با نقش manager مجوز سرویس پرداخت ندارد. لاگین موقت سرویس از مسیر صدور توکن S4 انجام می‌شود؛ هیچ JWT صادرشده توسط S3 یا امضای ناشناس مورد اعتماد نیست. + +درخواست با `Authorization: Bearer ` و HTTPS ارسال می‌شود. access پنج دقیقه اعتبار دارد؛ refresh با هر بار استفاده می‌چرخد و نمونه قبلی در blacklist قرار می‌گیرد. مقدار `X-Correlation-ID` را برای ردیابی بفرستید، بدون ثبت توکن، رمز یا داده حساس در لاگ. نبود یا نامعتبر بودن توکن 401 و فقدان نقش 403 است. جزئیات payload و پاسخ در `openapi/s4_rsk.yaml` هستند؛ قابلیت idempotency، callback، قرارداد صادرکننده مشترک و صدور machine-to-machine هنوز باید جداگانه پیاده‌سازی یا توافق شوند و نباید از این پیش‌نویس نتیجه بگیرید کامل‌اند. + +پیش از اتصال واقعی، تیم‌ها باید درباره identity provider، نوع و توزیع کلیدها، issuer/audience جدا برای S3، scope و حداقل دسترسی، انقضای کوتاه، چرخش و ابطال کلید و اعتبارنامه، TLS، محدودسازی نرخ و نظارت توافق کنند. استفاده از حساب انسانی یا به اشتراک گذاشتن کلید امضای S4 با S3 مجاز نیست. دسترسی و اعتبارنامه‌های آزمایشی در secret manager یا محیط محلی و خارج از Git نگهداری شوند. diff --git a/docs/adr/ADR-001-authentication.md b/docs/adr/ADR-001-authentication.md index 517ceb0..7c76f60 100644 --- a/docs/adr/ADR-001-authentication.md +++ b/docs/adr/ADR-001-authentication.md @@ -1,6 +1,7 @@ # ADR-001: Initial management API authentication -Status: implemented baseline for review; service-to-service authentication pending. +Status: superseded by the JWT implementation. See docs/reports/jwt-authentication.md and +contracts/s3-s4-jwt-draft.md. The historical session-based decision follows. The management API uses Django sessions and DRF SessionAuthentication. Unsafe requests from authenticated clients require Django's CSRF cookie and diff --git a/docs/reports/jwt-authentication.md b/docs/reports/jwt-authentication.md new file mode 100644 index 0000000..47e9ce0 --- /dev/null +++ b/docs/reports/jwt-authentication.md @@ -0,0 +1,23 @@ +# راهنمای احراز هویت JWT در S4-RSK + +API از Bearer JWT استفاده می‌کند. ورود به پنل Django همچنان session و CSRF خود را دارد؛ ورود به پنل به معنی دریافت توکن API نیست. ارتباط S3 پیش‌نویس است: `contracts/s3-s4-jwt-draft.md`. + +## آماده‌سازی + +1. از ریشه مخزن `docker compose up -d --build` را اجرا کنید. وابستگی جدید در `requirements.txt` ثبت شده است. +2. مهاجرت‌های جدید از جمله blacklist باید اجرا شوند: `docker compose exec -w /app/s4_rsk s4-rsk python manage.py migrate`. +3. در محیط توسعه یک مدیر بسازید: `docker compose exec -w /app/s4_rsk s4-rsk python manage.py createsuperuser`. رمز را به صورت تعاملی وارد کنید و در مخزن ننویسید. +4. به `http://localhost:8084/admin/` وارد شوید. در Groups یک گروه دقیقاً با نام `manager` بسازید، سپس در Users آن را به کاربر تخصیص دهید. داشتن superuser به تنهایی دسترسی به قوانین را نمی‌دهد. +5. برای ساخت کاربر معمولی در پنل Users > Add user را بزنید؛ نقش مناسب را فقط مدیر به کاربر تخصیص می‌دهد. برای حساب سرویس پرداخت گروه جداگانه `payment_service` لازم است و به آن `manager` ندهید. + +## ورود و Swagger + +1. `http://localhost:8084/api/docs/` را باز کنید. +2. مسیر `POST /api/v1/auth/token/` را با username و password اجرا کنید. خروجی access و refresh دارد. این دو را محرمانه نگه دارید. +3. در Authorize مقدار access را وارد کنید؛ درخواست‌ها با `Authorization: Bearer ` ارسال می‌شوند. `GET /api/v1/risk-rules` برای manager است. +4. access پنج دقیقه عمر دارد. برای دریافت جفت جدید، `POST /api/v1/auth/token/refresh/` را با بدنه `{"refresh":""}` اجرا کنید و هر دو توکن جدید را جایگزین کنید. refresh قبلی پس از چرخش باطل می‌شود. +5. برای خروج `POST /api/v1/auth/token/logout/` را با refresh جاری اجرا کنید. این کار refresh را باطل می‌کند؛ access صادرشده تا پایان اعتبار پنج دقیقه‌ای معتبر می‌ماند. + +توکن نامعتبر یا فاقد اعتبار 401 و کاربر بدون نقش مورد نیاز 403 می‌گیرد. تغییر رمز عبور و غیرفعال‌شدن کاربر اعتبار توکن را هنگام احراز هویت بررسی می‌کند. از انتشار توکن، قرار دادن آن در Git، لاگ، URL یا تصاویر صفحه خودداری کنید. در محیط واقعی HTTPS الزامی است؛ در مرورگر از ذخیره طولانی‌مدت توکن در localStorage خودداری کنید. + +کلید امضا از `JWT_SIGNING_KEY` خوانده می‌شود؛ فقط در حالت توسعه در نبود آن از `SECRET_KEY` استفاده می‌شود. با `DEBUG=False` کلید مستقل الزامی است. کلید تصادفی را در secret manager قرار دهید، نه در مخزن. issuer و audience به `labbank-s4-rsk` و `labbank-s4-rsk-api` محدودند. نرخ درخواست مسیرهای توکن در هر فرایند با cache پیش‌فرض محدود است؛ برای چند worker و استقرار واقعی cache مشترک، محدودسازی در gateway و پایش لازم است. برای پاک‌سازی blacklist منقضی، `python manage.py flushexpiredtokens` را به صورت دوره‌ای اجرا کنید. diff --git a/docs/us-02a-risk-rules.md b/docs/us-02a-risk-rules.md index 7979f61..fd71408 100644 --- a/docs/us-02a-risk-rules.md +++ b/docs/us-02a-risk-rules.md @@ -3,9 +3,9 @@ Owner: Ali. Reviewer: Abolfazl. US-02A is a plan identifier, not a Jira key. `GET /api/v1/risk-rules?limit=50&cursor=...` reads PostgreSQL records. It requires -an active session user in the exact `manager` group. Anonymous/inactive sessions -return 403 `UNAUTHORIZED`; authenticated users without that role return 403 -`FORBIDDEN`. Session behavior and pending S3 auth are documented in ADR-001. +an active bearer JWT user in the exact `manager` group. Missing/invalid credentials +return 401 `UNAUTHORIZED`; authenticated users without that role return 403 +`FORBIDDEN`. See the JWT guide and the draft S3 contract for authentication details. The response is `{ "items": [...], "next_cursor": null }`. Follow the opaque `next_cursor` using the same limit until null. The default page size is 50 and @@ -29,9 +29,8 @@ After migrating a **development database**, opt in to the fixture: Do not load fixtures into shared/production databases. Loading this fixture again resets its two fixed development records. No account/password is seeded. -For Swagger, create an interactive staff account and explicitly assign manager -as described in the README. Copy that account's session cookie only into local -Bruno variables, never into tracked collection files. +For Swagger, create an account and assign manager as described in the JWT guide. +Keep bearer tokens only in local secret variables, never in tracked collection files. Independent acceptance: migrate, load the fixture, log in, list two records, then verify forbidden/anonymous requests and follow a one-item cursor page. diff --git a/frontend/src/api/schema.d.ts b/frontend/src/api/schema.d.ts index cda6d16..943f5f7 100644 --- a/frontend/src/api/schema.d.ts +++ b/frontend/src/api/schema.d.ts @@ -4,6 +4,147 @@ */ export interface paths { + "/auth/token/": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** Obtain access and refresh JWTs */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": { + username: string; + /** Format: password */ + password: string; + }; + }; + }; + responses: { + /** @description Access and refresh JWTs */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + access: string; + refresh: string; + }; + }; + }; + /** @description Invalid credentials */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/auth/token/refresh/": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** Rotate a refresh token and obtain new tokens */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": { + refresh: string; + }; + }; + }; + responses: { + /** @description New access and refresh JWTs */ + 200: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Invalid or revoked refresh token */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/auth/token/logout/": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** Revoke a refresh token */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": { + refresh: string; + }; + }; + }; + responses: { + /** @description Refresh token revoked */ + 200: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/risk-assessments": { parameters: { query?: never; @@ -597,7 +738,7 @@ export interface components { "application/problem+json": components["schemas"]["Problem"]; }; }; - /** @description No valid session (`UNAUTHORIZED`) or missing role (`FORBIDDEN`). */ + /** @description The authenticated caller lacks the required role (`FORBIDDEN`). */ Forbidden: { headers: { [name: string]: unknown; diff --git a/openapi/s4_rsk.yaml b/openapi/s4_rsk.yaml index 3aa9410..7b07a39 100644 --- a/openapi/s4_rsk.yaml +++ b/openapi/s4_rsk.yaml @@ -12,13 +12,12 @@ info: every mutating POST accepts `Idempotency-Key`, lists use `limit` (max 200) and `cursor`, and field names are snake_case. - Authentication (ADR-001): Django session. A missing/invalid session and a missing role both - return 403; clients tell them apart by the problem `code` (`UNAUTHORIZED` or `FORBIDDEN`). + Authentication: Bearer JWT. Missing or invalid tokens return 401; insufficient role returns 403. servers: - url: http://localhost:8084/api/v1 description: Local development security: - - sessionAuth: [] + - bearerAuth: [] tags: - name: Risk Assessments description: Evaluate a transfer and read persisted decisions (loop endpoint with S3-PAY). @@ -35,13 +34,69 @@ tags: - name: Operations description: Liveness and readiness probes. paths: + /auth/token/: + post: + security: [] + summary: Obtain access and refresh JWTs + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [username, password] + properties: + username: {type: string} + password: {type: string, format: password} + responses: + '200': + description: Access and refresh JWTs + content: + application/json: + schema: + type: object + required: [access, refresh] + properties: + access: {type: string} + refresh: {type: string} + '401': {description: Invalid credentials} + /auth/token/refresh/: + post: + security: [] + summary: Rotate a refresh token and obtain new tokens + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [refresh] + properties: + refresh: {type: string} + responses: + '200': {description: New access and refresh JWTs} + '401': {description: Invalid or revoked refresh token} + /auth/token/logout/: + post: + security: [] + summary: Revoke a refresh token + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [refresh] + properties: + refresh: {type: string} + responses: + '200': {description: Refresh token revoked} /risk-assessments: post: tags: [Risk Assessments] operationId: createRiskAssessment security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Evaluate a transfer and persist the initial decision description: | Called by S3-PAY before executing a transfer. S4-RSK evaluates the transfer against the @@ -242,8 +297,7 @@ paths: tags: [Risk Rules] operationId: createRiskRule security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Create a risk rule parameters: - $ref: '#/components/parameters/IdempotencyKey' @@ -271,8 +325,7 @@ paths: tags: [Risk Rules] operationId: updateRiskRule security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Change a rule with optimistic revision control description: A stale `expected_revision` is rejected with 409 `CONFLICT`. parameters: @@ -357,8 +410,7 @@ paths: tags: [Blocked Identifiers] operationId: createBlockedIdentifier security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Block an IBAN description: Only one active record may exist per identifier; a second one returns 409 `CONFLICT`. parameters: @@ -387,8 +439,7 @@ paths: tags: [Blocked Identifiers] operationId: deactivateBlockedIdentifier security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Deactivate a blocked identifier (soft delete, audit is kept) parameters: - name: id @@ -433,8 +484,7 @@ paths: tags: [Manual Review] operationId: claimReviewItem security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Claim a queue item atomically description: Only one operator can claim an item; a second claim returns 409 `CONFLICT`. parameters: @@ -463,8 +513,7 @@ paths: tags: [Manual Review] operationId: decideReviewItem security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Final human decision on a claimed item description: Only the operator who claimed the item may decide; a reason is mandatory. parameters: @@ -573,8 +622,7 @@ paths: tags: [Deliveries] operationId: retryDelivery security: - - sessionAuth: [] - csrfToken: [] + - bearerAuth: [] summary: Retry a failed delivery manually parameters: - name: delivery_id @@ -644,18 +692,10 @@ paths: $ref: '#/components/responses/ServiceUnavailable' components: securitySchemes: - sessionAuth: - type: apiKey - in: cookie - name: sessionid - description: Django session cookie (ADR-001). Unsafe methods also require the CSRF token. - csrfToken: - type: apiKey - in: header - name: X-CSRFToken - description: | - Value of the `csrftoken` cookie, required on unsafe methods (POST, PATCH, DELETE) for - session-authenticated clients (ADR-001). Without it the service answers 403. + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT headers: XCorrelationId: description: Trace identifier of this response, also present in the logs. @@ -711,7 +751,7 @@ components: detail: start must not be later than end. correlation_id: 7f3c1e52-5a0b-4a4f-9c1e-0d2b6a9f1c33 Forbidden: - description: No valid session (`UNAUTHORIZED`) or missing role (`FORBIDDEN`). + description: The authenticated caller lacks the required role (`FORBIDDEN`). content: application/problem+json: schema: diff --git a/requirements.txt b/requirements.txt index 9c9641f..bcdbde8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,6 +8,7 @@ click==8.5.0 # Core Framework Django==5.1.15 djangorestframework==3.17.2 +djangorestframework-simplejwt==5.5.1 # OpenAPI 3.1 Documentation drf-spectacular==0.30.0 fastapi==0.141.1 @@ -43,4 +44,4 @@ ruff>=0.6.9 pytest>=8.3.3 pytest-django>=4.9.0 model-bakery>=1.19.5 -pytest-cov>=5.1.0 \ No newline at end of file +pytest-cov>=5.1.0 diff --git a/s4_rsk/.env.example b/s4_rsk/.env.example index b87ea07..abc2849 100644 --- a/s4_rsk/.env.example +++ b/s4_rsk/.env.example @@ -3,6 +3,7 @@ SERVICE_NAME=s4-rsk PORT=8084 DEBUG=True SECRET_KEY=django-insecure-change-me-in-production-s4-rsk-labbank +# JWT_SIGNING_KEY must be a separate strong secret when DEBUG=False. ALLOWED_HOSTS=localhost,127.0.0.1,s4-rsk,0.0.0.0 # --- CORS (frontend dev server origins, comma separated) --- diff --git a/s4_rsk/assessments/tests.py b/s4_rsk/assessments/tests.py index e046438..c3980f5 100644 --- a/s4_rsk/assessments/tests.py +++ b/s4_rsk/assessments/tests.py @@ -2,7 +2,7 @@ from unittest.mock import patch import pytest -from django.contrib.auth.models import User +from django.contrib.auth.models import Group, User from django.urls import reverse from rest_framework.test import APIClient @@ -31,6 +31,7 @@ def api_client(db) -> APIClient: password="test-password", is_staff=True, ) + user.groups.add(Group.objects.get_or_create(name="payment_service")[0]) client.force_authenticate(user=user) return client @@ -62,7 +63,7 @@ def test_unauthenticated_request_returns_403(self, valid_payload: dict): response = unauthenticated_client.post(url, data=valid_payload, format="json") - assert response.status_code == 403 + assert response.status_code == 401 assert RiskAssessment.objects.count() == 0 def test_create_assessment_success_persists_records(self, api_client: APIClient, valid_payload: dict): diff --git a/s4_rsk/assessments/views.py b/s4_rsk/assessments/views.py index e343faf..7849874 100644 --- a/s4_rsk/assessments/views.py +++ b/s4_rsk/assessments/views.py @@ -1,5 +1,6 @@ from drf_spectacular.utils import OpenApiParameter, OpenApiTypes, extend_schema from rest_framework import status +from rest_framework.permissions import IsAuthenticated from rest_framework.request import Request from rest_framework.response import Response from rest_framework.views import APIView @@ -11,6 +12,7 @@ RiskAssessmentResponseSerializer, ) from assessments.services import evaluate_and_persist_assessment +from common.permissions import IsPaymentService class RiskAssessmentCreateAPIView(APIView): @@ -19,6 +21,8 @@ class RiskAssessmentCreateAPIView(APIView): Evaluates a payment transaction and persists the initial risk decision (US-01A). """ + permission_classes = (IsAuthenticated, IsPaymentService) + @extend_schema( operation_id="createRiskAssessment", summary="Evaluate transaction risk and persist decision", @@ -64,6 +68,8 @@ class RiskAssessmentDetailAPIView(APIView): Retrieves a previously evaluated risk assessment and its reasons (US-01A). """ + permission_classes = (IsAuthenticated, IsPaymentService) + @extend_schema( operation_id="getRiskAssessmentById", summary="Retrieve a risk assessment decision by decision_id", diff --git a/s4_rsk/common/auth_views.py b/s4_rsk/common/auth_views.py new file mode 100644 index 0000000..776b73f --- /dev/null +++ b/s4_rsk/common/auth_views.py @@ -0,0 +1,18 @@ +from rest_framework.throttling import AnonRateThrottle +from rest_framework_simplejwt.views import ( + TokenBlacklistView, + TokenObtainPairView, + TokenRefreshView, +) + + +class LoginView(TokenObtainPairView): + throttle_classes = [AnonRateThrottle] + + +class RefreshView(TokenRefreshView): + throttle_classes = [AnonRateThrottle] + + +class LogoutView(TokenBlacklistView): + throttle_classes = [AnonRateThrottle] diff --git a/s4_rsk/common/permissions.py b/s4_rsk/common/permissions.py index 022bdad..e996c3c 100644 --- a/s4_rsk/common/permissions.py +++ b/s4_rsk/common/permissions.py @@ -6,11 +6,16 @@ class IsRiskManager(BasePermission): message = "The manager role is required." + def has_permission(self, request, view): + user = request.user + return bool(user and user.is_authenticated and user.is_active and user.groups.filter(name="manager").exists()) + + +class IsPaymentService(BasePermission): + """Only a separately provisioned payment service account may assess transfers.""" + def has_permission(self, request, view): user = request.user return bool( - user - and user.is_authenticated - and user.is_active - and user.groups.filter(name="manager").exists() + user and user.is_authenticated and user.is_active and user.groups.filter(name="payment_service").exists() ) diff --git a/s4_rsk/common/test_jwt_auth.py b/s4_rsk/common/test_jwt_auth.py new file mode 100644 index 0000000..a670511 --- /dev/null +++ b/s4_rsk/common/test_jwt_auth.py @@ -0,0 +1,74 @@ +from datetime import timedelta + +import jwt +import pytest +from django.conf import settings +from django.contrib.auth.models import Group +from rest_framework.test import APIClient +from rest_framework_simplejwt.tokens import AccessToken + + +@pytest.mark.django_db +def test_jwt_login_permissions_rotation_and_logout(django_user_model): + user = django_user_model.objects.create_user("manager", password="example-password-123") + user.groups.add(Group.objects.create(name="manager")) + client = APIClient() + assert client.get("/api/v1/risk-rules").status_code == 401 + login = client.post( + "/api/v1/auth/token/", {"username": "manager", "password": "example-password-123"}, format="json" + ) + assert login.status_code == 200 + tokens = login.json() + client.credentials(HTTP_AUTHORIZATION=f"Bearer {tokens['access']}") + assert client.get("/api/v1/risk-rules").status_code == 200 + assert client.get("/api/v1/risk-assessments/00000000-0000-0000-0000-000000000000").status_code == 403 + client.credentials() + refresh = client.post("/api/v1/auth/token/refresh/", {"refresh": tokens["refresh"]}, format="json") + assert refresh.status_code == 200 + assert client.post("/api/v1/auth/token/refresh/", {"refresh": tokens["refresh"]}, format="json").status_code == 401 + rotated = refresh.json()["refresh"] + assert client.post("/api/v1/auth/token/logout/", {"refresh": rotated}, format="json").status_code == 200 + assert client.post("/api/v1/auth/token/refresh/", {"refresh": rotated}, format="json").status_code == 401 + + +@pytest.mark.django_db +def test_invalid_token_and_non_manager_are_rejected(django_user_model): + django_user_model.objects.create_user("other", password="example-password-123") + client = APIClient() + client.credentials(HTTP_AUTHORIZATION="Bearer invalid") + assert client.get("/api/v1/risk-rules").status_code == 401 + client.credentials() + token = client.post( + "/api/v1/auth/token/", {"username": "other", "password": "example-password-123"}, format="json" + ).json()["access"] + client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}") + assert client.get("/api/v1/risk-rules").status_code == 403 + + +@pytest.mark.django_db +def test_payment_service_role_has_access_but_cannot_list_rules(django_user_model): + user = django_user_model.objects.create_user("s3-service", password="example-password-123") + user.groups.add(Group.objects.create(name="payment_service")) + client = APIClient() + token = client.post( + "/api/v1/auth/token/", {"username": "s3-service", "password": "example-password-123"}, format="json" + ).json()["access"] + client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}") + assert client.get("/api/v1/risk-rules").status_code == 403 + assert client.get("/api/v1/risk-assessments/00000000-0000-0000-0000-000000000000").status_code == 404 + + +@pytest.mark.django_db +def test_expired_and_wrong_audience_tokens_are_rejected(django_user_model): + user = django_user_model.objects.create_user("jwt-check") + user.groups.add(Group.objects.create(name="manager")) + client = APIClient() + expired = AccessToken.for_user(user) + expired.set_exp(lifetime=timedelta(seconds=-1)) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {expired}") + assert client.get("/api/v1/risk-rules").status_code == 401 + wrong_audience = AccessToken.for_user(user) + wrong_audience["aud"] = "different-service" + token = jwt.encode(wrong_audience.payload, settings.JWT_SIGNING_KEY, algorithm="HS256") + client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}") + assert client.get("/api/v1/risk-rules").status_code == 401 diff --git a/s4_rsk/config/settings.py b/s4_rsk/config/settings.py index e840426..ec67ca2 100644 --- a/s4_rsk/config/settings.py +++ b/s4_rsk/config/settings.py @@ -1,3 +1,4 @@ +from datetime import timedelta from pathlib import Path from zoneinfo import ZoneInfo @@ -47,6 +48,7 @@ "django.contrib.staticfiles", # Third-party apps "rest_framework", + "rest_framework_simplejwt.token_blacklist", "corsheaders", "drf_spectacular", # S4-RSK Local Apps @@ -115,7 +117,7 @@ # Django REST Framework Settings REST_FRAMEWORK = { "DEFAULT_AUTHENTICATION_CLASSES": [ - "rest_framework.authentication.SessionAuthentication", + "rest_framework_simplejwt.authentication.JWTAuthentication", ], "DEFAULT_PERMISSION_CLASSES": [ "rest_framework.permissions.IsAuthenticated", @@ -129,6 +131,24 @@ "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema", "DEFAULT_PAGINATION_CLASS": "common.pagination.LabBankCursorPagination", "EXCEPTION_HANDLER": "common.exceptions.rfc9457_exception_handler", + "DEFAULT_THROTTLE_RATES": {"anon": "10/minute"}, +} + +JWT_SIGNING_KEY = env("JWT_SIGNING_KEY", default=SECRET_KEY if DEBUG else None) +if not DEBUG and (not JWT_SIGNING_KEY or JWT_SIGNING_KEY == SECRET_KEY): + from django.core.exceptions import ImproperlyConfigured + + raise ImproperlyConfigured("Set a distinct JWT_SIGNING_KEY when DEBUG=False.") + +SIMPLE_JWT = { + "ACCESS_TOKEN_LIFETIME": timedelta(minutes=5), + "REFRESH_TOKEN_LIFETIME": timedelta(hours=8), + "ROTATE_REFRESH_TOKENS": True, + "BLACKLIST_AFTER_ROTATION": True, + "CHECK_REVOKE_TOKEN": True, + "ISSUER": "labbank-s4-rsk", + "AUDIENCE": "labbank-s4-rsk-api", + "SIGNING_KEY": JWT_SIGNING_KEY, } # GEN-01: OpenAPI 3.1 Specification Settings diff --git a/s4_rsk/config/urls.py b/s4_rsk/config/urls.py index d8104e6..68978e8 100644 --- a/s4_rsk/config/urls.py +++ b/s4_rsk/config/urls.py @@ -4,6 +4,7 @@ from django.urls import include, path from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView +from common.auth_views import LoginView, LogoutView, RefreshView from common.views import health_view, ready_view urlpatterns = [ @@ -14,6 +15,9 @@ # GEN-01: OpenAPI 3.1 Schema & Swagger UI path("api/schema/", SpectacularAPIView.as_view(), name="schema"), path("api/docs/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"), + path("api/v1/auth/token/", LoginView.as_view(), name="token_obtain_pair"), + path("api/v1/auth/token/refresh/", RefreshView.as_view(), name="token_refresh"), + path("api/v1/auth/token/logout/", LogoutView.as_view(), name="token_blacklist"), # GEN-02: All Service Endpoints under /api/v1/ path("api/v1/", include("assessments.urls")), path("api/v1/", include("rules.urls")), diff --git a/s4_rsk/rules/tests.py b/s4_rsk/rules/tests.py index 025edfa..0d5bf35 100644 --- a/s4_rsk/rules/tests.py +++ b/s4_rsk/rules/tests.py @@ -9,6 +9,7 @@ from django.utils import timezone from drf_spectacular.generators import SchemaGenerator from rest_framework.test import APIClient +from rest_framework_simplejwt.tokens import AccessToken from .models import RiskRule @@ -28,7 +29,7 @@ def manager(django_user_model): @pytest.fixture def manager_client(manager): client = APIClient(enforce_csrf_checks=True) - assert client.login(username=manager.username, password="test-only-password") + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(manager)}") return client @@ -68,7 +69,7 @@ def test_empty_configuration_has_explicit_empty_page(manager_client): def test_anonymous_session_is_denied(): response = APIClient().get(URL) - assert response.status_code == 403 + assert response.status_code == 401 assert response["Content-Type"] == "application/problem+json" assert response.json()["code"] == "UNAUTHORIZED" @@ -79,7 +80,7 @@ def test_non_managers_are_denied(role, django_user_model): if role: user.groups.add(Group.objects.get_or_create(name=role)[0]) client = APIClient() - client.force_login(user) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(user)}") response = client.get(URL) assert response.status_code == 403 assert response.json()["code"] == "FORBIDDEN" @@ -90,7 +91,7 @@ def test_superuser_without_manager_group_is_denied(django_user_model): "admin", is_staff=True, is_superuser=True ) client = APIClient() - client.force_login(user) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(user)}") response = client.get(URL) assert response.status_code == 403 assert response.json()["code"] == "FORBIDDEN" @@ -100,7 +101,7 @@ def test_inactive_manager_session_is_denied(manager_client, manager): manager.is_active = False manager.save(update_fields=["is_active"]) response = manager_client.get(URL) - assert response.status_code == 403 + assert response.status_code == 401 assert response.json()["code"] == "UNAUTHORIZED" @@ -138,16 +139,15 @@ def test_bad_cursor_returns_problem_details(manager_client): assert response.json()["code"] == "NOT_FOUND" -def test_authenticated_unsafe_requests_still_require_csrf(manager_client): +def test_authenticated_unsafe_requests_are_not_allowed(manager_client): response = manager_client.post(URL, {}, format="json") - assert response.status_code == 403 - assert response.json()["code"] == "FORBIDDEN" + assert response.status_code == 405 assert RiskRule.objects.count() == 0 def test_endpoint_does_not_allow_writes(manager): client = APIClient() - client.force_login(manager) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(manager)}") response = client.post(URL, {"name": "Unauthorized write"}, format="json") assert response.status_code == 405 assert RiskRule.objects.count() == 0 @@ -192,7 +192,7 @@ def test_configuration_survives_a_new_python_process(): def test_schema_exposes_actual_cursor_envelope(): schema = SchemaGenerator().get_schema(request=None, public=True) operation = schema["paths"][URL]["get"] - assert operation["security"] == [{"cookieAuth": []}] + assert operation["security"] == [{"jwtAuth": []}] response = operation["responses"]["200"]["content"]["application/json"]["schema"] definition = schema["components"]["schemas"][response["$ref"].rsplit("/", 1)[1]] assert set(definition["properties"]) == {"items", "next_cursor"} From b0dfc8ae5b3c02fe2f46fbafd2d57c5270d933b7 Mon Sep 17 00:00:00 2001 From: AliJohari05 Date: Fri, 6 Nov 2026 22:01:33 +0330 Subject: [PATCH 3/6] feat(rules): add rule management and revision history --- contracts/openapi.yaml | 199 +++++++++++++++++- docs/reports/us-02-api-testing.md | 55 +++++ docs/test-matrices/README.md | 14 ++ docs/test-matrices/us-02.md | 24 +++ docs/test-matrices/us-08-draft.md | 15 ++ docs/us-02b-rule-history.md | 7 + frontend/src/api/schema.d.ts | 21 +- openapi/s4_rsk.yaml | 22 +- pytest.ini | 6 + s4_rsk/rules/migrations/0002_rulerevision.py | 32 +++ .../migrations/0003_rulecreaterequest.py | 27 +++ .../migrations/0004_protect_rule_revision.py | 27 +++ s4_rsk/rules/models.py | 35 +++ s4_rsk/rules/serializers.py | 46 +++- s4_rsk/rules/services.py | 59 ++++++ s4_rsk/rules/test_rule_api.py | 189 +++++++++++++++++ s4_rsk/rules/test_rule_history.py | 121 +++++++++++ s4_rsk/rules/test_validators.py | 20 ++ s4_rsk/rules/tests.py | 10 +- s4_rsk/rules/urls.py | 5 +- s4_rsk/rules/validators.py | 11 + s4_rsk/rules/views.py | 111 +++++++++- 22 files changed, 1039 insertions(+), 17 deletions(-) create mode 100644 docs/reports/us-02-api-testing.md create mode 100644 docs/test-matrices/README.md create mode 100644 docs/test-matrices/us-02.md create mode 100644 docs/test-matrices/us-08-draft.md create mode 100644 docs/us-02b-rule-history.md create mode 100644 pytest.ini create mode 100644 s4_rsk/rules/migrations/0002_rulerevision.py create mode 100644 s4_rsk/rules/migrations/0003_rulecreaterequest.py create mode 100644 s4_rsk/rules/migrations/0004_protect_rule_revision.py create mode 100644 s4_rsk/rules/services.py create mode 100644 s4_rsk/rules/test_rule_api.py create mode 100644 s4_rsk/rules/test_rule_history.py create mode 100644 s4_rsk/rules/test_validators.py create mode 100644 s4_rsk/rules/validators.py diff --git a/contracts/openapi.yaml b/contracts/openapi.yaml index 4e84e14..80bfce7 100644 --- a/contracts/openapi.yaml +++ b/contracts/openapi.yaml @@ -153,8 +153,6 @@ paths: /api/v1/risk-rules: get: operationId: risk_rules_list - description: List stored rule configuration, including disabled and future rules. - Requires the manager group; this endpoint does not evaluate rules. parameters: - in: header name: X-Correlation-ID @@ -214,6 +212,126 @@ paths: schema: $ref: '#/components/schemas/Problem' description: '' + post: + operationId: createRiskRule + parameters: + - in: header + name: Idempotency-Key + schema: + type: string + description: UUID for safe retries + tags: + - api + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RiskRuleInput' + required: true + security: + - jwtAuth: [] + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/RiskRule' + description: '' + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Problem' + description: '' + '409': + content: + application/json: + schema: + $ref: '#/components/schemas/Problem' + description: '' + /api/v1/risk-rules/{rule_id}: + patch: + operationId: updateRiskRule + parameters: + - in: path + name: rule_id + schema: + type: string + format: uuid + required: true + tags: + - api + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchedRiskRulePatch' + security: + - jwtAuth: [] + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/RiskRule' + description: '' + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Problem' + description: '' + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Problem' + description: '' + '409': + content: + application/json: + schema: + $ref: '#/components/schemas/Problem' + description: '' + /api/v1/risk-rules/{rule_id}/audit: + get: + operationId: listRiskRuleAudit + parameters: + - name: cursor + required: false + in: query + description: The pagination cursor value. + schema: + type: string + - name: limit + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - in: path + name: rule_id + schema: + type: string + format: uuid + required: true + tags: + - api + security: + - jwtAuth: [] + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedRuleRevisionList' + description: '' + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Problem' + description: '' /health: get: operationId: health_retrieve @@ -346,6 +464,37 @@ components: type: - string - 'null' + PaginatedRuleRevisionList: + type: object + required: + - items + - next_cursor + properties: + items: + type: array + items: + $ref: '#/components/schemas/RuleRevision' + next_cursor: + type: + - string + - 'null' + PatchedRiskRulePatch: + type: object + properties: + expected_revision: + type: integer + minimum: 1 + name: + type: string + maxLength: 120 + parameters: + type: object + additionalProperties: {} + enabled: + type: boolean + effective_at: + type: string + format: date-time Problem: type: object properties: @@ -535,6 +684,52 @@ components: - revision - type - updated_at + RiskRuleInput: + type: object + properties: + name: + type: string + maxLength: 120 + type: + $ref: '#/components/schemas/TypeEnum' + parameters: + type: object + additionalProperties: {} + enabled: + type: boolean + effective_at: + type: string + format: date-time + required: + - name + - parameters + - type + RuleRevision: + type: object + properties: + revision: + type: integer + readOnly: true + actor: + type: string + readOnly: true + changed_at: + type: string + format: date-time + readOnly: true + before: + oneOf: + - {} + - type: 'null' + readOnly: true + after: + readOnly: true + required: + - actor + - after + - before + - changed_at + - revision TokenBlacklist: type: object properties: diff --git a/docs/reports/us-02-api-testing.md b/docs/reports/us-02-api-testing.md new file mode 100644 index 0000000..18d000c --- /dev/null +++ b/docs/reports/us-02-api-testing.md @@ -0,0 +1,55 @@ +# راهنمای آزمون API قوانین ریسک + +این مراحل برای محیط توسعه و داده آزمایشی است؛ POST و PATCH داده واقعی ایجاد یا تغییر می‌دهند. اجرای تست خودکار را روی PostgreSQL آزمایشی جداگانه انجام دهید. تست API با ابزار مرورگر یا PowerShell جایگزین تست واحد و integration خودکار نیست. + +## آماده‌سازی + +1. از ریشه پروژه `docker compose up -d --build` را اجرا کنید. فایل‌های migration جدید باید اجرا شوند؛ در صورت لزوم `docker compose exec -w /app/s4_rsk s4-rsk python manage.py migrate` را اجرا کنید. +2. مطابق [راهنمای JWT](jwt-authentication.md) کاربر فعال بسازید و در Django admin گروه دقیق `manager` را به او اختصاص دهید. superuser بودن به‌تنهایی کافی نیست. +3. `http://localhost:8084/api/docs/` را باز کنید. در `POST /api/v1/auth/token/` نام کاربری و رمز را وارد کنید و access را از پاسخ بردارید. در Authorize مقدار access را وارد کنید. در هدر درخواست باید `Authorization: Bearer ` ارسال شود. توکن را در Git و تصویر قرار ندهید. +4. برای پایان اعتبار access، با refresh فعلی `POST /api/v1/auth/token/refresh/` را اجرا و access و refresh جدید را جایگزین کنید. جزئیات و خروج در راهنمای JWT آمده است. + +## گردش آزمون در Swagger + +1. `GET /api/v1/risk-rules` را با Try it out و Execute اجرا کنید. پاسخ 200 و `items` و `next_cursor` است. `limit` اندازه صفحه است و `cursor` پاسخ قبلی را برای صفحه بعد می‌دهید. +2. `POST /api/v1/risk-rules` را اجرا کنید. `Idempotency-Key` اختیاری و از نوع UUID است. برای retry امن یک UUID جدید برای هر عملیات منطقی تولید کنید؛ تکرار همان کلید با همان بدنه پاسخ 201 اولیه را برمی‌گرداند و بدنه یا کاربر متفاوت 409 می‌دهد. بدون کلید، تکرار POST یک قانون جدید می‌سازد. + +```json +{"name":"Demo limit","type":"AMOUNT_LIMIT","parameters":{"max_amount_irr":100},"enabled":false} +``` + +شناسه `id` و `revision` پاسخ را نگه دارید. `effective_at` اختیاری است و اگر ارائه شود باید تاریخ و زمان معتبر باشد. + +3. `PATCH /api/v1/risk-rules/{rule_id}` را با id و revision آخر اجرا کنید: + +```json +{"expected_revision":1,"parameters":{"max_amount_irr":200}} +``` + +باید 200 و revision برابر ۲ دریافت کنید. حداقل یک فیلد قابل ویرایش لازم است؛ `type`، `actor` و `revision` قابل ارسال برای ویرایش نیستند. ارسال مجدد revision قدیمی باید 409 بدهد. + +4. `GET /api/v1/risk-rules/{rule_id}/audit` را اجرا کنید: نسخه‌های ۲ و ۱ به ترتیب نزولی نمایش داده می‌شوند؛ actor شناسه کاربر احراز هویت‌شده و before/after وضعیت‌های ثبت‌شده هستند. +5. جداگانه مقدار ۰، مقدار بیش از `9223372036854775807`، بدنه ناقص، کاربر بدون manager و درخواست بدون توکن را تست کنید. به‌ترتیب خطای 400، 400، 400، 403 و 401 انتظار می‌رود. پاسخ خطا `application/problem+json` دارد. UUID معتبر ولی ناموجود برای PATCH یا audit پاسخ 404 می‌دهد. ارسال UUID نامعتبر در مسیر ممکن است پیش از رسیدن به view نیز 404 بدهد. + +## نمونه PowerShell + +پس از گرفتن access در متغیر `$access`، دستورهای زیر را اجرا کنید. برای تولید کلید از PowerShell استفاده کنید و در تکرار همان عملیات `$key` را عوض نکنید: + +```powershell +$base = 'http://localhost:8084/api/v1' +$headers = @{ Authorization = "Bearer $access" } +$key = [guid]::NewGuid().ToString() +$createHeaders = @{ Authorization = "Bearer $access"; 'Idempotency-Key' = $key } +$body = @{ name='Demo limit'; type='AMOUNT_LIMIT'; parameters=@{ max_amount_irr=100 }; enabled=$false } | ConvertTo-Json -Depth 5 +$rule = Invoke-RestMethod -Method Post -Uri "$base/risk-rules" -Headers $createHeaders -ContentType 'application/json' -Body $body +$id = $rule.id +$patch = @{ expected_revision=$rule.revision; parameters=@{ max_amount_irr=200 } } | ConvertTo-Json -Depth 5 +Invoke-RestMethod -Method Patch -Uri "$base/risk-rules/$id" -Headers $headers -ContentType 'application/json' -Body $patch +Invoke-RestMethod -Method Get -Uri "$base/risk-rules/$id/audit" -Headers $headers +``` + +## تست خودکار و migration + +در ریشه، با `.venv` و تنظیمات اتصال به PostgreSQL آزمایشی: `python -m pytest --create-db`. تنظیمات پروژه `--reuse-db` دارد؛ پس از migration تازه `--create-db` دیتابیس **تست** را بازسازی می‌کند. هرگز آن را به دیتابیس غیرآزمایشی اشاره ندهید. از `s4_rsk` نیز `..\.venv\Scripts\python.exe -m pytest --create-db` قابل استفاده است. تست subprocess مربوط به manage.py عمداً پوشه `s4_rsk` را به‌عنوان working directory تنظیم می‌کند. + +تاریخچه تنها برای تغییرات مسیر سرویس تضمین می‌شود؛ تغییر مستقیم ORM/SQL قانون را دور می‌زند. trigger PostgreSQL از UPDATE و DELETE معمولی روی تاریخچه جلوگیری می‌کند اما از TRUNCATE یا غیرفعال‌کردن trigger توسط مالک جلوگیری نمی‌کند. در production دسترسی دیتابیس و فرآیند migration را تفکیک و محدود کنید. داده‌های قدیمی گذشته‌نگر بازسازی نشده‌اند. diff --git a/docs/test-matrices/README.md b/docs/test-matrices/README.md new file mode 100644 index 0000000..7be8999 --- /dev/null +++ b/docs/test-matrices/README.md @@ -0,0 +1,14 @@ +# ماتریس‌های تست + +ماتریس تست جدول توافق بر رفتار مورد انتظار قبل از نوشتن یا هنگام بازبینی تست است. سناریو یک وضعیت کلی است؛ هر case با ورودی، پیش‌شرط و نتیجه مشخص، نمونه قابل بررسی آن سناریو است. برای مثال سناریوی «اعتبار مبلغ سقف» شامل caseهای ۰، ۱ و بیشتر از حداکثر است. مقدار مرزی و همسایه‌های آن و ورودی خالی یا نامعتبر را جداگانه بررسی کنید. + +ماتریس جای اجرای تست را نمی‌گیرد: برای هر ردیف، نتیجه را با پاسخ API و در صورت لزوم وضعیت دیتابیس مقایسه کنید و در ستون تست خودکار به نام تست واقعی ارجاع دهید. هر عضو می‌تواند فایل `us-XX.md` بسازد، استوری و فرض‌ها را بنویسد و جدول زیر را تکمیل کند. نتیجه‌های نامشخص را با تیم توافق کنید؛ به‌جای حدس زدن آن‌ها را قطعی اعلام نکنید. + +| شناسه | سناریو و پیش‌شرط | ورودی | نتیجه مورد انتظار | سطح / تست خودکار | +|---|---|---|---|---| +| XX-01 | ... | ... | ... | unit / integration / دستی؛ نام تست | + +تست unit رفتار یک جزء، integration همکاری چند جزء مانند API و PostgreSQL، و تست دستی/End-to-End مسیر کاربر را بررسی می‌کند. از داده و محیط آزمایشی استفاده کنید. پس از تغییر قرارداد، این جدول و تست‌ها را به‌روز کنید. + +- [US-02 مدیریت قوانین](us-02.md) +- [US-08 توضیح‌پذیری تصمیم، پیش‌نویس](us-08-draft.md) diff --git a/docs/test-matrices/us-02.md b/docs/test-matrices/us-02.md new file mode 100644 index 0000000..a432de7 --- /dev/null +++ b/docs/test-matrices/us-02.md @@ -0,0 +1,24 @@ +# ماتریس تست US-02: مدیریت قوانین ریسک + +وضعیت: مبنای تست پیاده‌سازی حاضر. همه عملیات API به کاربر فعال در گروه `manager` نیاز دارند. `AMOUNT_LIMIT` نیازمند `max_amount_irr` صحیح بین ۱ و `2^63-1` است. هر نوشتن موفق از سرویس، revision و تاریخچه را در یک تراکنش ثبت می‌کند. + +| شناسه | سناریو | ورودی | نتیجه مورد انتظار | پوشش | +|---|---|---|---|---| +| R02-01 | ساخت معتبر | مبلغ ۱ یا `2^63-1` | موفق، revision ۱ و یک تاریخچه | unit و integration: `test_valid_amount_boundaries`, `test_valid_boundaries` | +| R02-02 | مرز نامعتبر | ۰، منفی، `2^63`، اعشاری، بولی، فاقد مبلغ | 400 یا خطای اعتبارسنجی؛ بدون داده جدید | `test_invalid_parameters_rejected_without_side_effects`, `test_invalid_amount_parameters_do_not_create_rule_or_history` | +| R02-03 | قالب پارامتر | آرایه یا null | خطای اعتبارسنجی | تست‌های نامعتبر بالا | +| R02-04 | اصلاح معتبر | revision فعلی و مبلغ جدید | 200، افزایش revision و ثبت before/after و actor | `test_create_update_and_read_audit` | +| R02-05 | رقابت کاربران | expected_revision قدیمی | 409 بدون تغییر یا تاریخچه تازه | `test_stale_and_invalid_patch_leave_original_unchanged` | +| R02-06 | اصلاح نامعتبر | مقدار نامعتبر یا actor در بدنه | 400؛ وضعیت ثابت می‌ماند | همان تست R02-05 | +| R02-07 | retry درخواست ایجاد | کلید و بدنه یکسان | همان 201 و همان پاسخ؛ فقط یک قانون و تاریخچه | `test_post_replay_and_conflict` | +| R02-08 | استفاده مجدد از کلید | همان کلید با بدنه یا کاربر متفاوت | 409 و افشاشدن پاسخ قبلی رخ نمی‌دهد | `test_post_replay_and_conflict`, `test_same_key_cannot_leak_response_to_another_manager` | +| R02-09 | احراز هویت و دسترسی | بدون JWT یا بدون گروه manager | به‌ترتیب 401 و 403 | `test_auth_and_missing_rule`, `test_non_managers_are_denied` | +| R02-10 | قانون ناموجود | UUID ناشناخته | 404 برای ویرایش و تاریخچه | `test_auth_and_missing_rule` | +| R02-11 | صفحه‌بندی تاریخچه | limit=1 و cursor | نسخه‌ها به‌ترتیب نزولی بدون تکرار | `test_audit_cursor_pages` | +| R02-12 | شکست نوشتن تاریخچه | خطای ثبت تاریخچه | rollback تغییر قانون | `test_history_failure_rolls_back_existing_rule_update` | +| R02-13 | تغییر مستقیم تاریخچه در PostgreSQL | UPDATE یا DELETE | خطای دیتابیس | `test_database_rejects_history_update_and_delete` | +| R02-14 | قانون قدیمی بدون تاریخچه | تغییر قانون موجود با revision ۳ | فقط نسخه ۴ و snapshot قبل/بعد ثبت می‌شود | `test_existing_rule_gets_history_only_when_updated` | +| R02-15 | دو درخواست هم‌زمان | دو POST با کلید یکسان | دو پاسخ یکسان و تنها یک قانون | `test_concurrent_post_same_key_creates_one_rule` | +| R02-16 | دو ویرایش هم‌زمان | هر دو با revision یکسان | یک 200 و یک 409؛ فقط یک نسخه جدید | `test_concurrent_patch_allows_only_one_revision` | + +محدودیت: ORM و SQL مستقیم روی خود RiskRule هنوز می‌توانند مسیر سرویس را دور بزنند. trigger تاریخچه، UPDATE/DELETE معمولی را منع می‌کند اما مالک دیتابیس می‌تواند trigger را غیرفعال کند و TRUNCATE نیز حفاظت نشده است؛ نقش‌ها و مجوزهای جداگانه برای استقرار واقعی لازم‌اند. diff --git a/docs/test-matrices/us-08-draft.md b/docs/test-matrices/us-08-draft.md new file mode 100644 index 0000000..38058a1 --- /dev/null +++ b/docs/test-matrices/us-08-draft.md @@ -0,0 +1,15 @@ +# پیش‌نویس ماتریس US-08: توضیح‌پذیری تصمیم + +این پیش‌نویس مشخصات نهایی استوری نیست. در مدل فعلی `DecisionReason` فیلدهای code، message، rule_id، rule_revision و rule_snapshot وجود دارند؛ وجود این مدل به‌تنهایی اثبات کامل بودن API یا برآورده‌شدن استوری نیست. endpoint، نقش‌های مجاز، قرارداد پاسخ، تعداد علت‌ها و نحوه نمایش داده حساس باید با تیم توافق شوند. + +| شناسه | سناریوی پیشنهادی | ورودی / شرایط | نتیجه پیشنهادی؛ نیازمند توافق | سطح پیشنهادی | +|---|---|---|---|---| +| R08-01 | دلیل تصمیم منطبق با قانون | تصمیم با یک قانون منطبق | code، message و شناسه و نسخه قانون مرتبط قابل مشاهده | integration | +| R08-02 | چند دلیل | بیش از یک قانون منطبق | همه دلایل طبق ترتیب توافقی برگردند | integration | +| R08-03 | هیچ قانونی منطبق نیست | تصمیم بدون تطبیق | دلیل یا پیام قراردادی مشخص و بدون داده ساختگی | unit و integration | +| R08-04 | حفظ سابقه پس از ویرایش قانون | تغییر پارامتر بعد از تصمیم | snapshot و revision تصمیم قدیمی تغییر نکنند | integration | +| R08-05 | تصمیم ناموجود | UUID معتبر اما ناموجود | پاسخ 404 قراردادی | API | +| R08-06 | مجوز مشاهده | بدون JWT، نقش غیرمجاز، نقش مجاز | به‌ترتیب 401، 403 و پاسخ مجاز | API | +| R08-07 | داده ناقص یا مقدار مرزی | پیام خالی/طول حداکثر/بیش از سقف و rule_id خالی | مطابق اعتبارسنجی و قرارداد نهایی | unit | +| R08-08 | داده حساس | اطلاعات پرداخت در جزئیات | خروجی صرفاً شامل داده مجاز طبق سیاست توافق‌شده | امنیتی/API | +| R08-09 | صفحه‌بندی | صفر، یک و تعداد زیاد دلایل | نتیجه و ترتیب مطابق قرارداد صفحه‌بندی | integration، در صورت پشتیبانی | diff --git a/docs/us-02b-rule-history.md b/docs/us-02b-rule-history.md new file mode 100644 index 0000000..c3b149f --- /dev/null +++ b/docs/us-02b-rule-history.md @@ -0,0 +1,7 @@ +# US-02B: Rule revision history + +Manager-only POST, PATCH and audit endpoints use the transactional services in `rules.services`. They validate rule parameters, lock the rule during updates, reject stale revisions and record the actor and before/after snapshots atomically. Existing rules do not receive fabricated history: their first service update records the previous and new state. The `AMOUNT_LIMIT` parameter is `max_amount_irr` and must be an integer between 1 and the signed 64-bit maximum. `BLOCKLIST` currently accepts any object; more specific semantics need team agreement. + +The PostgreSQL migration rejects ordinary UPDATE and DELETE statements on history rows. It does not restrict TRUNCATE or a database owner who disables the trigger. Direct ORM, bulk and SQL writes to `RiskRule` bypass service validation and history; production deployment needs separate, restricted database roles and an agreed way to enforce the service boundary. Database-owner privileges are not an audit protection boundary. + +See [API testing](reports/us-02-api-testing.md) and the [test matrix](test-matrices/us-02.md). Tests run from the root or `s4_rsk`; after new migrations, `pytest --create-db` recreates the **test database**. Use a dedicated PostgreSQL instance and preserve important data. The subprocess test sets its working directory to `s4_rsk` so its relative `manage.py` path works from either directory. diff --git a/frontend/src/api/schema.d.ts b/frontend/src/api/schema.d.ts index 943f5f7..e0fcb6e 100644 --- a/frontend/src/api/schema.d.ts +++ b/frontend/src/api/schema.d.ts @@ -625,6 +625,23 @@ export interface components { items: components["schemas"]["RiskRule"][]; next_cursor: string | null; }; + RuleRevision: { + revision: number; + /** @description Authenticated user ID */ + actor: string; + /** Format: date-time */ + changed_at: string; + before: { + [key: string]: unknown; + } | null; + after: { + [key: string]: unknown; + }; + }; + RuleRevisionPage: { + items: components["schemas"]["RuleRevision"][]; + next_cursor: string | null; + }; BlockedIdentifierInput: { /** @enum {string} */ kind: "IBAN"; @@ -1037,7 +1054,7 @@ export interface operations { * "name": "Max single transfer", * "type": "AMOUNT_LIMIT", * "parameters": { - * "max_amount": 50000000 + * "max_amount_irr": 50000000 * }, * "enabled": true, * "effective_at": "2026-10-01T00:00:00Z", @@ -1138,7 +1155,7 @@ export interface operations { [name: string]: unknown; }; content: { - "application/json": components["schemas"]["RiskRulePage"]; + "application/json": components["schemas"]["RuleRevisionPage"]; }; }; 403: components["responses"]["Forbidden"]; diff --git a/openapi/s4_rsk.yaml b/openapi/s4_rsk.yaml index 7b07a39..aaf7329 100644 --- a/openapi/s4_rsk.yaml +++ b/openapi/s4_rsk.yaml @@ -282,7 +282,7 @@ paths: name: Max single transfer type: AMOUNT_LIMIT parameters: - max_amount: 50000000 + max_amount_irr: 50000000 enabled: true effective_at: '2026-10-01T00:00:00Z' revision: 1 @@ -376,7 +376,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RiskRulePage' + $ref: '#/components/schemas/RuleRevisionPage' '403': $ref: '#/components/responses/Forbidden' '404': @@ -1041,6 +1041,24 @@ components: $ref: '#/components/schemas/RiskRule' next_cursor: type: [string, 'null'] + RuleRevision: + type: object + required: [revision, actor, changed_at, before, after] + properties: + revision: {type: integer, minimum: 1} + actor: {type: string, description: Authenticated user ID} + changed_at: {type: string, format: date-time} + before: {type: [object, 'null'], additionalProperties: true} + after: {type: object, additionalProperties: true} + RuleRevisionPage: + type: object + required: [items, next_cursor] + properties: + items: + type: array + items: + $ref: '#/components/schemas/RuleRevision' + next_cursor: {type: [string, 'null']} BlockedIdentifierInput: type: object required: [kind, value, reason] diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 0000000..a2d78ce --- /dev/null +++ b/pytest.ini @@ -0,0 +1,6 @@ +[pytest] +DJANGO_SETTINGS_MODULE = config.settings +pythonpath = s4_rsk +testpaths = s4_rsk +python_files = tests.py test_*.py *_tests.py +addopts = --reuse-db -v diff --git a/s4_rsk/rules/migrations/0002_rulerevision.py b/s4_rsk/rules/migrations/0002_rulerevision.py new file mode 100644 index 0000000..ea2ea35 --- /dev/null +++ b/s4_rsk/rules/migrations/0002_rulerevision.py @@ -0,0 +1,32 @@ +# Generated by Django 5.1.15 on 2026-11-06 17:36 + +import django.db.models.deletion +from django.conf import settings +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('rules', '0001_initial'), + migrations.swappable_dependency(settings.AUTH_USER_MODEL), + ] + + operations = [ + migrations.CreateModel( + name='RuleRevision', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('revision', models.PositiveIntegerField()), + ('changed_at', models.DateTimeField(auto_now_add=True)), + ('before', models.JSONField(blank=True, null=True)), + ('after', models.JSONField()), + ('actor', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, to=settings.AUTH_USER_MODEL)), + ('rule', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='history', to='rules.riskrule')), + ], + options={ + 'ordering': ['-revision'], + 'constraints': [models.UniqueConstraint(fields=('rule', 'revision'), name='unique_rule_revision'), models.CheckConstraint(condition=models.Q(('revision__gte', 1)), name='rule_history_revision_positive')], + }, + ), + ] diff --git a/s4_rsk/rules/migrations/0003_rulecreaterequest.py b/s4_rsk/rules/migrations/0003_rulecreaterequest.py new file mode 100644 index 0000000..26c14cf --- /dev/null +++ b/s4_rsk/rules/migrations/0003_rulecreaterequest.py @@ -0,0 +1,27 @@ +# Generated by Django 5.1.15 on 2026-11-06 18:06 + +import django.db.models.deletion +from django.conf import settings +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('rules', '0002_rulerevision'), + migrations.swappable_dependency(settings.AUTH_USER_MODEL), + ] + + operations = [ + migrations.CreateModel( + name='RuleCreateRequest', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('key', models.UUIDField(unique=True)), + ('fingerprint', models.CharField(max_length=64)), + ('response', models.JSONField(null=True)), + ('created_at', models.DateTimeField(auto_now_add=True)), + ('actor', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, to=settings.AUTH_USER_MODEL)), + ], + ), + ] diff --git a/s4_rsk/rules/migrations/0004_protect_rule_revision.py b/s4_rsk/rules/migrations/0004_protect_rule_revision.py new file mode 100644 index 0000000..dcf5594 --- /dev/null +++ b/s4_rsk/rules/migrations/0004_protect_rule_revision.py @@ -0,0 +1,27 @@ +from django.db import migrations + + +def protect(apps, schema_editor): + if schema_editor.connection.vendor != "postgresql": + return + schema_editor.execute(""" + CREATE FUNCTION rules_reject_history_mutation() RETURNS trigger AS $$ + BEGIN + RAISE EXCEPTION 'Rule revisions are append-only'; + END; + $$ LANGUAGE plpgsql; + CREATE TRIGGER rules_revision_append_only + BEFORE UPDATE OR DELETE ON rules_rulerevision + FOR EACH ROW EXECUTE FUNCTION rules_reject_history_mutation(); + """) + + +def unprotect(apps, schema_editor): + if schema_editor.connection.vendor == "postgresql": + schema_editor.execute("DROP TRIGGER IF EXISTS rules_revision_append_only ON rules_rulerevision;") + schema_editor.execute("DROP FUNCTION IF EXISTS rules_reject_history_mutation();") + + +class Migration(migrations.Migration): + dependencies = [("rules", "0003_rulecreaterequest")] + operations = [migrations.RunPython(protect, unprotect)] diff --git a/s4_rsk/rules/models.py b/s4_rsk/rules/models.py index ef70083..8d8cdee 100644 --- a/s4_rsk/rules/models.py +++ b/s4_rsk/rules/models.py @@ -1,9 +1,12 @@ from typing import ClassVar +from django.conf import settings from django.db import models from django.utils import timezone from uuid6 import uuid7 +from .validators import validate_rule_parameters + class RiskRule(models.Model): class Type(models.TextChoices): @@ -35,3 +38,35 @@ class Meta: def __str__(self): return f"{self.name} (revision {self.revision})" + + def clean(self): + super().clean() + validate_rule_parameters(self.type, self.parameters) + + +class RuleRevision(models.Model): + """A recorded before/after state for an explicit rule management operation.""" + + rule = models.ForeignKey(RiskRule, on_delete=models.PROTECT, related_name="history") + revision = models.PositiveIntegerField() + actor = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT) + changed_at = models.DateTimeField(auto_now_add=True) + before = models.JSONField(null=True, blank=True) + after = models.JSONField() + + class Meta: + ordering: ClassVar = ["-revision"] + constraints: ClassVar = [ + models.UniqueConstraint(fields=["rule", "revision"], name="unique_rule_revision"), + models.CheckConstraint(condition=models.Q(revision__gte=1), name="rule_history_revision_positive"), + ] + + +class RuleCreateRequest(models.Model): + """Persist a successful response for safe POST retries.""" + + key = models.UUIDField(unique=True) + actor = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT) + fingerprint = models.CharField(max_length=64) + response = models.JSONField(null=True) + created_at = models.DateTimeField(auto_now_add=True) diff --git a/s4_rsk/rules/serializers.py b/s4_rsk/rules/serializers.py index 98eb2e6..67fde53 100644 --- a/s4_rsk/rules/serializers.py +++ b/s4_rsk/rules/serializers.py @@ -1,6 +1,6 @@ from rest_framework import serializers -from .models import RiskRule +from .models import RiskRule, RuleRevision class RiskRuleSerializer(serializers.ModelSerializer): @@ -18,3 +18,47 @@ class Meta: "updated_at", ) read_only_fields = fields + + +class StrictSerializer(serializers.Serializer): + def to_internal_value(self, data): + if isinstance(data, dict): + unknown = set(data) - set(self.fields) + if unknown: + raise serializers.ValidationError({key: "Unexpected field." for key in sorted(unknown)}) + return super().to_internal_value(data) + + +class RiskRuleInputSerializer(StrictSerializer): + name = serializers.CharField(max_length=120) + type = serializers.ChoiceField(choices=RiskRule.Type.choices) + parameters = serializers.DictField(allow_empty=True) + enabled = serializers.BooleanField(required=False) + effective_at = serializers.DateTimeField(required=False) + + +class RiskRulePatchSerializer(StrictSerializer): + expected_revision = serializers.IntegerField(min_value=1) + name = serializers.CharField(max_length=120, required=False) + parameters = serializers.DictField(allow_empty=True, required=False) + enabled = serializers.BooleanField(required=False) + effective_at = serializers.DateTimeField(required=False) + + def validate_expected_revision(self, value): + if isinstance(self.initial_data.get("expected_revision"), bool): + raise serializers.ValidationError("Must be a positive integer.") + return value + + def validate(self, attrs): + if len(attrs) == 1: + raise serializers.ValidationError("At least one editable field is required.") + return attrs + + +class RuleRevisionSerializer(serializers.ModelSerializer): + actor = serializers.CharField(source="actor_id", read_only=True) + + class Meta: + model = RuleRevision + fields = ("revision", "actor", "changed_at", "before", "after") + read_only_fields = fields diff --git a/s4_rsk/rules/services.py b/s4_rsk/rules/services.py new file mode 100644 index 0000000..f725ead --- /dev/null +++ b/s4_rsk/rules/services.py @@ -0,0 +1,59 @@ +import json + +from django.core.exceptions import PermissionDenied, ValidationError +from django.core.serializers.json import DjangoJSONEncoder +from django.db import transaction + +from common.exceptions import LabBankAPIException + +from .models import RiskRule, RuleRevision + +_EDITABLE_FIELDS = frozenset({"name", "type", "parameters", "enabled", "effective_at"}) + + +def _check_actor(actor): + if ( + not actor + or not actor.is_authenticated + or not actor.is_active + or not actor.groups.filter(name="manager").exists() + ): + raise PermissionDenied("An active manager is required.") + + +def _snapshot(rule): + values = {field: getattr(rule, field) for field in _EDITABLE_FIELDS} + values.update(id=str(rule.pk), revision=rule.revision) + return json.loads(json.dumps(values, cls=DjangoJSONEncoder)) + + +@transaction.atomic +def create_rule(*, actor, **fields): + _check_actor(actor) + if set(fields) - _EDITABLE_FIELDS: + raise ValidationError("Unexpected rule fields.") + rule = RiskRule(**fields) + rule.full_clean(exclude=["parameters"]) + rule.save() + RuleRevision.objects.create(rule=rule, revision=rule.revision, actor=actor, before=None, after=_snapshot(rule)) + return rule + + +@transaction.atomic +def update_rule(*, actor, rule_id, expected_revision, changes): + _check_actor(actor) + if isinstance(expected_revision, bool) or not isinstance(expected_revision, int) or expected_revision < 1: + raise ValidationError("Expected revision must be a positive integer.") + if not isinstance(changes, dict) or not changes or set(changes) - _EDITABLE_FIELDS: + raise ValidationError("Supply only editable rule fields.") + rule = RiskRule.objects.select_for_update().get(pk=rule_id) + if rule.revision != expected_revision: + raise LabBankAPIException("CONFLICT", "Conflict", "Rule revision is stale.", 409, "conflict") + before = _snapshot(rule) + for field, value in changes.items(): + setattr(rule, field, value) + rule.revision += 1 + rule.full_clean(exclude=["parameters"]) + rule.save() + RuleRevision.objects.create(rule=rule, revision=rule.revision, actor=actor, before=before, after=_snapshot(rule)) + return rule diff --git a/s4_rsk/rules/test_rule_api.py b/s4_rsk/rules/test_rule_api.py new file mode 100644 index 0000000..2f46f8c --- /dev/null +++ b/s4_rsk/rules/test_rule_api.py @@ -0,0 +1,189 @@ +import uuid +from concurrent.futures import ThreadPoolExecutor +from threading import Barrier + +import pytest +from django.contrib.auth.models import Group +from django.db import DatabaseError, connection, transaction +from rest_framework.test import APIClient +from rest_framework_simplejwt.tokens import AccessToken + +from .models import RiskRule, RuleRevision + +URL = "/api/v1/risk-rules" +pytestmark = pytest.mark.django_db + + +@pytest.fixture +def client_manager(django_user_model): + user = django_user_model.objects.create_user("api-manager") + user.groups.add(Group.objects.get_or_create(name="manager")[0]) + client = APIClient() + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(user)}") + return client, user + + +@pytest.fixture +def payload(): + return {"name": "limit", "type": "AMOUNT_LIMIT", "parameters": {"max_amount_irr": 100}} + + +def test_create_update_and_read_audit(client_manager, payload): + client, user = client_manager + created = client.post(URL, payload, format="json") + assert created.status_code == 201 + rule_id = created.data["id"] + assert created.data["revision"] == 1 + changed = client.patch( + f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount_irr": 200}}, format="json" + ) + assert changed.status_code == 200 + assert changed.data["revision"] == 2 + history = client.get(f"{URL}/{rule_id}/audit").data["items"] + assert [item["revision"] for item in history] == [2, 1] + assert history[0]["actor"] == str(user.pk) + assert history[0]["before"]["parameters"] == {"max_amount_irr": 100} + assert history[0]["after"]["parameters"] == {"max_amount_irr": 200} + assert history[1]["before"] is None + + +def test_post_replay_and_conflict(client_manager, payload): + client, _ = client_manager + key = str(uuid.uuid4()) + first = client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key) + replay = client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key) + assert first.status_code == replay.status_code == 201 + assert first.data == replay.data + conflict = client.post(URL, {**payload, "name": "different"}, format="json", HTTP_IDEMPOTENCY_KEY=key) + assert conflict.status_code == 409 + assert RiskRule.objects.count() == RuleRevision.objects.count() == 1 + + +def test_same_key_cannot_leak_response_to_another_manager(client_manager, payload, django_user_model): + client, _ = client_manager + key = str(uuid.uuid4()) + assert client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key).status_code == 201 + other = django_user_model.objects.create_user("other-manager") + other.groups.add(Group.objects.get(name="manager")) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(other)}") + assert client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key).status_code == 409 + + +@pytest.mark.parametrize( + "parameters", + [{}, {"max_amount_irr": 0}, {"max_amount_irr": -1}, {"max_amount_irr": True}, {"max_amount_irr": 2**63}, []], +) +def test_invalid_parameters_rejected_without_side_effects(client_manager, payload, parameters): + client, _ = client_manager + response = client.post(URL, {**payload, "parameters": parameters}, format="json") + assert response.status_code == 400 + assert not RiskRule.objects.exists() + assert not RuleRevision.objects.exists() + + +def test_stale_and_invalid_patch_leave_original_unchanged(client_manager, payload): + client, _ = client_manager + rule_id = client.post(URL, payload, format="json").data["id"] + assert client.patch(f"{URL}/{rule_id}", {"expected_revision": 2, "name": "new"}, format="json").status_code == 409 + assert ( + client.patch( + f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount_irr": 0}}, format="json" + ).status_code + == 400 + ) + assert client.patch(f"{URL}/{rule_id}", {"expected_revision": 1, "actor": 1}, format="json").status_code == 400 + assert ( + client.patch(f"{URL}/{rule_id}", {"expected_revision": True, "name": "bad"}, format="json").status_code == 400 + ) + rule = RiskRule.objects.get(pk=rule_id) + assert (rule.revision, rule.name, rule.history.count()) == (1, "limit", 1) + + +def test_auth_and_missing_rule(client_manager, payload, django_user_model): + client, _ = client_manager + missing = uuid.uuid4() + assert client.get(f"{URL}/{missing}/audit").status_code == 404 + assert client.patch(f"{URL}/{missing}", {"expected_revision": 1, "name": "x"}, format="json").status_code == 404 + assert APIClient().post(URL, payload, format="json").status_code == 401 + other = django_user_model.objects.create_user("ordinary-user") + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(other)}") + assert client.post(URL, payload, format="json").status_code == 403 + assert client.get(f"{URL}/{missing}/audit").status_code == 403 + + +def test_audit_cursor_pages(client_manager, payload): + client, _ = client_manager + rule_id = client.post(URL, payload, format="json").data["id"] + client.patch(f"{URL}/{rule_id}", {"expected_revision": 1, "name": "second"}, format="json") + first = client.get(f"{URL}/{rule_id}/audit", {"limit": 1}).data + second = client.get(f"{URL}/{rule_id}/audit", {"limit": 1, "cursor": first["next_cursor"]}).data + assert first["items"][0]["revision"] == 2 + assert second["items"][0]["revision"] == 1 + assert second["next_cursor"] is None + + +def test_database_rejects_history_update_and_delete(client_manager, payload): + if connection.vendor != "postgresql": + pytest.skip("PostgreSQL trigger") + client, _ = client_manager + client.post(URL, payload, format="json") + for operation in (lambda: RuleRevision.objects.update(after={}), lambda: RuleRevision.objects.all().delete()): + with pytest.raises(DatabaseError), transaction.atomic(): + operation() + assert RuleRevision.objects.count() == 1 + + +@pytest.mark.django_db(transaction=True) +def test_concurrent_post_same_key_creates_one_rule(client_manager, payload): + from django.db import close_old_connections + + _, user = client_manager + token = str(AccessToken.for_user(user)) + key = str(uuid.uuid4()) + barrier = Barrier(2) + + def create(): + close_old_connections() + try: + client = APIClient() + client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}") + barrier.wait(timeout=15) + response = client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key) + return response.status_code, response.data["id"] + finally: + close_old_connections() + + with ThreadPoolExecutor(max_workers=2) as pool: + results = list(pool.map(lambda _: create(), range(2))) + assert results[0] == results[1] + assert results[0][0] == 201 + assert RiskRule.objects.count() == RuleRevision.objects.count() == 1 + + +@pytest.mark.django_db(transaction=True) +def test_concurrent_patch_allows_only_one_revision(client_manager, payload): + from django.db import close_old_connections + + client, user = client_manager + rule_id = client.post(URL, payload, format="json").data["id"] + token = str(AccessToken.for_user(user)) + barrier = Barrier(2) + + def update(name): + close_old_connections() + try: + concurrent_client = APIClient() + concurrent_client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}") + barrier.wait(timeout=15) + return concurrent_client.patch( + f"{URL}/{rule_id}", {"expected_revision": 1, "name": name}, format="json" + ).status_code + finally: + close_old_connections() + + with ThreadPoolExecutor(max_workers=2) as pool: + statuses = list(pool.map(update, ["first", "second"])) + assert sorted(statuses) == [200, 409] + rule = RiskRule.objects.get(pk=rule_id) + assert rule.revision == 2 + assert rule.history.count() == 2 diff --git a/s4_rsk/rules/test_rule_history.py b/s4_rsk/rules/test_rule_history.py new file mode 100644 index 0000000..b543ca2 --- /dev/null +++ b/s4_rsk/rules/test_rule_history.py @@ -0,0 +1,121 @@ +from unittest.mock import patch + +import pytest +from django.contrib.auth.models import Group +from django.core.exceptions import PermissionDenied, ValidationError +from django.db import IntegrityError, transaction + +from common.exceptions import LabBankAPIException + +from .models import RiskRule, RuleRevision +from .services import create_rule, update_rule + +pytestmark = pytest.mark.django_db + + +@pytest.fixture +def manager(django_user_model): + user = django_user_model.objects.create_user("history-manager") + user.groups.add(Group.objects.create(name="manager")) + return user + + +def test_create_and_update_record_before_after_and_actor(manager): + rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 100}) + created = rule.history.get(revision=1) + assert created.before is None + assert created.after["parameters"] == {"max_amount_irr": 100} + assert created.actor == manager + assert created.changed_at is not None + + update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"parameters": {"max_amount_irr": 200}}) + rule.refresh_from_db() + updated = rule.history.get(revision=2) + assert rule.revision == 2 + assert updated.before["parameters"] == {"max_amount_irr": 100} + assert updated.before["revision"] == 1 + assert updated.after["parameters"] == {"max_amount_irr": 200} + assert updated.after["revision"] == 2 + assert created.after["parameters"] == {"max_amount_irr": 100} + + +@pytest.mark.parametrize( + "parameters", + [ + {}, + {"max_amount_irr": 0}, + {"max_amount_irr": -1}, + {"max_amount_irr": True}, + {"max_amount_irr": 1.5}, + {"max_amount_irr": 2**63}, + [], + None, + ], +) +def test_invalid_amount_parameters_do_not_create_rule_or_history(manager, parameters): + with pytest.raises(ValidationError): + create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters=parameters) + assert RiskRule.objects.count() == 0 + assert RuleRevision.objects.count() == 0 + + +@pytest.mark.parametrize("amount", [1, 2**63 - 1]) +def test_valid_amount_boundaries(manager, amount): + rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount_irr": amount}) + assert rule.history.count() == 1 + + +def test_stale_revision_and_invalid_update_do_not_change_state(manager): + rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 100}) + with pytest.raises(LabBankAPIException) as error: + update_rule(actor=manager, rule_id=rule.pk, expected_revision=2, changes={"name": "changed"}) + assert error.value.status_code == 409 + with pytest.raises(ValidationError): + update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"parameters": {"max_amount_irr": 0}}) + rule.refresh_from_db() + assert rule.revision == 1 + assert rule.name == "limit" + assert rule.history.count() == 1 + + +def test_history_failure_rolls_back_rule(manager): + with ( + patch("rules.services.RuleRevision.objects.create", side_effect=RuntimeError("failure")), + pytest.raises(RuntimeError), + ): + create_rule(actor=manager, name="blocklist", type="BLOCKLIST", parameters={}) + assert not RiskRule.objects.exists() + + +def test_history_failure_rolls_back_existing_rule_update(manager): + rule = create_rule(actor=manager, name="old", type="BLOCKLIST", parameters={}) + with ( + patch("rules.services.RuleRevision.objects.create", side_effect=RuntimeError("failure")), + pytest.raises(RuntimeError), + ): + update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"name": "new"}) + rule.refresh_from_db() + assert (rule.name, rule.revision, rule.history.count()) == ("old", 1, 1) + + +def test_existing_rule_gets_history_only_when_updated(manager): + rule = RiskRule.objects.create(name="old", type="BLOCKLIST", parameters={}, revision=3) + assert not rule.history.exists() + update_rule(actor=manager, rule_id=rule.pk, expected_revision=3, changes={"name": "new"}) + history = rule.history.get() + assert history.revision == 4 + assert history.before["name"] == "old" + assert history.after["name"] == "new" + + +def test_only_manager_can_write_history(django_user_model): + user = django_user_model.objects.create_user("not-manager") + with pytest.raises(PermissionDenied): + create_rule(actor=user, name="blocklist", type="BLOCKLIST", parameters={}) + assert not RiskRule.objects.exists() + + +def test_revision_unique_per_rule(manager): + rule = create_rule(actor=manager, name="blocklist", type="BLOCKLIST", parameters={}) + with transaction.atomic(), pytest.raises(IntegrityError): + RuleRevision.objects.create(rule=rule, revision=1, actor=manager, after={}) diff --git a/s4_rsk/rules/test_validators.py b/s4_rsk/rules/test_validators.py new file mode 100644 index 0000000..3294aed --- /dev/null +++ b/s4_rsk/rules/test_validators.py @@ -0,0 +1,20 @@ +import pytest +from django.core.exceptions import ValidationError + +from .validators import validate_rule_parameters + + +@pytest.mark.parametrize("amount", [1, 2**63 - 1]) +def test_valid_boundaries(amount): + validate_rule_parameters("AMOUNT_LIMIT", {"max_amount_irr": amount}) + + +@pytest.mark.parametrize("parameters", [None, [], {}, {"max_amount_irr": 0}, + {"max_amount_irr": True}, {"max_amount_irr": 2**63}]) +def test_invalid_validator_input(parameters): + with pytest.raises(ValidationError): + validate_rule_parameters("AMOUNT_LIMIT", parameters) + + +def test_blocklist_accepts_empty_object(): + validate_rule_parameters("BLOCKLIST", {}) diff --git a/s4_rsk/rules/tests.py b/s4_rsk/rules/tests.py index 0d5bf35..029afab 100644 --- a/s4_rsk/rules/tests.py +++ b/s4_rsk/rules/tests.py @@ -1,6 +1,7 @@ import os import subprocess import sys +from pathlib import Path import pytest from django.contrib.auth.models import Group @@ -139,17 +140,17 @@ def test_bad_cursor_returns_problem_details(manager_client): assert response.json()["code"] == "NOT_FOUND" -def test_authenticated_unsafe_requests_are_not_allowed(manager_client): +def test_invalid_create_is_rejected(manager_client): response = manager_client.post(URL, {}, format="json") - assert response.status_code == 405 + assert response.status_code == 400 assert RiskRule.objects.count() == 0 -def test_endpoint_does_not_allow_writes(manager): +def test_incomplete_create_is_rejected(manager): client = APIClient() client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(manager)}") response = client.post(URL, {"name": "Unauthorized write"}, format="json") - assert response.status_code == 405 + assert response.status_code == 400 assert RiskRule.objects.count() == 0 @@ -181,6 +182,7 @@ def test_configuration_survives_a_new_python_process(): f"from rules.models import RiskRule; assert RiskRule.objects.get(pk='{rule.id}').name == 'Persistent rule'", ], env=environment, + cwd=Path(__file__).resolve().parent.parent, capture_output=True, text=True, timeout=30, diff --git a/s4_rsk/rules/urls.py b/s4_rsk/rules/urls.py index c7fc1d9..b1859d5 100644 --- a/s4_rsk/rules/urls.py +++ b/s4_rsk/rules/urls.py @@ -1,8 +1,9 @@ - from django.urls import path -from .views import RiskRuleListView +from .views import RiskRuleAuditView, RiskRuleListView, RiskRuleUpdateView urlpatterns = [ path("risk-rules", RiskRuleListView.as_view(), name="risk-rule-list"), + path("risk-rules/", RiskRuleUpdateView.as_view(), name="risk-rule-update"), + path("risk-rules//audit", RiskRuleAuditView.as_view(), name="risk-rule-audit"), ] diff --git a/s4_rsk/rules/validators.py b/s4_rsk/rules/validators.py new file mode 100644 index 0000000..f83c3ae --- /dev/null +++ b/s4_rsk/rules/validators.py @@ -0,0 +1,11 @@ +from django.core.exceptions import ValidationError + + +def validate_rule_parameters(rule_type, parameters): + """Validate the currently agreed parameter structure for a new rule revision.""" + if not isinstance(parameters, dict): + raise ValidationError({"parameters": "Parameters must be a JSON object."}) + if rule_type == "AMOUNT_LIMIT": + amount = parameters.get("max_amount_irr") + if isinstance(amount, bool) or not isinstance(amount, int) or not 1 <= amount <= 2**63 - 1: + raise ValidationError({"parameters": "max_amount_irr must be a positive signed 64-bit integer."}) diff --git a/s4_rsk/rules/views.py b/s4_rsk/rules/views.py index 7e85bff..fa8b082 100644 --- a/s4_rsk/rules/views.py +++ b/s4_rsk/rules/views.py @@ -1,13 +1,32 @@ -from drf_spectacular.utils import extend_schema +import hashlib +import json +import uuid + +from django.core.exceptions import ValidationError as DjangoValidationError +from django.core.serializers.json import DjangoJSONEncoder +from django.db import transaction +from django.shortcuts import get_object_or_404 +from drf_spectacular.utils import OpenApiParameter, extend_schema +from rest_framework import serializers, status from rest_framework.generics import ListAPIView from rest_framework.permissions import IsAuthenticated +from rest_framework.response import Response +from rest_framework.views import APIView +from common.exceptions import LabBankAPIException +from common.pagination import LabBankCursorPagination from common.permissions import IsRiskManager from common.schema import CORRELATION_HEADERS from common.serializers import ProblemSerializer +from .models import RiskRule, RuleCreateRequest from .selectors import list_risk_rules -from .serializers import RiskRuleSerializer +from .serializers import RiskRuleInputSerializer, RiskRulePatchSerializer, RiskRuleSerializer, RuleRevisionSerializer +from .services import create_rule, update_rule + + +def _validation_error(exc): + raise serializers.ValidationError(getattr(exc, "message_dict", exc.messages)) from exc class RiskRuleListView(ListAPIView): @@ -19,8 +38,6 @@ def get_queryset(self): @extend_schema( operation_id="risk_rules_list", - description="List stored rule configuration, including disabled and future rules. Requires the manager group;" - " this endpoint does not evaluate rules.", parameters=CORRELATION_HEADERS, responses={ 200: RiskRuleSerializer(many=True), @@ -30,3 +47,89 @@ def get_queryset(self): ) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs) + + @extend_schema( + operation_id="createRiskRule", + request=RiskRuleInputSerializer, + parameters=[ + OpenApiParameter( + "Idempotency-Key", str, OpenApiParameter.HEADER, required=False, description="UUID for safe retries" + ) + ], + responses={201: RiskRuleSerializer, 400: ProblemSerializer, 409: ProblemSerializer}, + ) + def post(self, request): + serializer = RiskRuleInputSerializer(data=request.data) + serializer.is_valid(raise_exception=True) + key = request.headers.get("Idempotency-Key") + if key is not None: + try: + key = uuid.UUID(key) + except (ValueError, AttributeError): + raise serializers.ValidationError({"Idempotency-Key": "Must be a UUID."}) + fingerprint = hashlib.sha256( + json.dumps(request.data, sort_keys=True, separators=(",", ":"), cls=DjangoJSONEncoder).encode() + ).hexdigest() + try: + with transaction.atomic(): + record = None + if key is not None: + record, created = RuleCreateRequest.objects.get_or_create( + key=key, defaults={"actor": request.user, "fingerprint": fingerprint} + ) + if not created: + if record.actor_id != request.user.pk or record.fingerprint != fingerprint: + raise LabBankAPIException( + "CONFLICT", "Conflict", "Idempotency key already used.", 409, "conflict" + ) + return Response(record.response, status=status.HTTP_201_CREATED) + rule = create_rule(actor=request.user, **serializer.validated_data) + data = dict(RiskRuleSerializer(rule).data) + if record is not None: + record.response = data + record.save(update_fields=["response"]) + return Response(data, status=status.HTTP_201_CREATED) + except DjangoValidationError as exc: + _validation_error(exc) + + +class RiskRuleUpdateView(APIView): + permission_classes = (IsAuthenticated, IsRiskManager) + + @extend_schema( + operation_id="updateRiskRule", + request=RiskRulePatchSerializer, + responses={200: RiskRuleSerializer, 400: ProblemSerializer, 404: ProblemSerializer, 409: ProblemSerializer}, + ) + def patch(self, request, rule_id): + serializer = RiskRulePatchSerializer(data=request.data) + serializer.is_valid(raise_exception=True) + values = dict(serializer.validated_data) + revision = values.pop("expected_revision") + try: + rule = update_rule(actor=request.user, rule_id=rule_id, expected_revision=revision, changes=values) + except RiskRule.DoesNotExist: + get_object_or_404(RiskRule, pk=rule_id) + except DjangoValidationError as exc: + _validation_error(exc) + return Response(RiskRuleSerializer(rule).data) + + +class AuditPagination(LabBankCursorPagination): + ordering = ("-revision", "-id") + + +class RiskRuleAuditView(ListAPIView): + permission_classes = (IsAuthenticated, IsRiskManager) + serializer_class = RuleRevisionSerializer + pagination_class = AuditPagination + + def get_queryset(self): + rule = get_object_or_404(RiskRule, pk=self.kwargs["rule_id"]) + return rule.history.select_related("actor").all() + + @extend_schema( + operation_id="listRiskRuleAudit", responses={200: RuleRevisionSerializer(many=True), 404: ProblemSerializer} + ) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) From e8bd5e09021122683feefa06d70e3e1f82f37db4 Mon Sep 17 00:00:00 2001 From: AliJohari05 Date: Sat, 7 Nov 2026 17:45:37 +0330 Subject: [PATCH 4/6] fix(rules): standardize amount parameter and pytest configuration --- docs/reports/us-02-api-testing.md | 10 ++--- docs/test-matrices/us-02.md | 2 +- docs/us-02b-rule-history.md | 6 ++- frontend/src/api/schema.d.ts | 4 +- openapi/s4_rsk.yaml | 4 +- pytest.ini | 6 --- .../risk_rules_cases.py | 18 +++------ s4_rsk/pytest.ini | 3 +- s4_rsk/rules/fixtures/dev_risk_rules.json | 2 +- .../migrations/0005_standardize_max_amount.py | 23 +++++++++++ s4_rsk/rules/test_max_amount_migration.py | 39 +++++++++++++++++++ s4_rsk/rules/test_rule_api.py | 12 +++--- s4_rsk/rules/test_rule_history.py | 28 ++++++------- s4_rsk/rules/test_validators.py | 12 ++++-- s4_rsk/rules/tests.py | 4 +- s4_rsk/rules/validators.py | 6 ++- 16 files changed, 122 insertions(+), 57 deletions(-) delete mode 100644 pytest.ini create mode 100644 s4_rsk/rules/migrations/0005_standardize_max_amount.py create mode 100644 s4_rsk/rules/test_max_amount_migration.py diff --git a/docs/reports/us-02-api-testing.md b/docs/reports/us-02-api-testing.md index 18d000c..70e2caa 100644 --- a/docs/reports/us-02-api-testing.md +++ b/docs/reports/us-02-api-testing.md @@ -15,7 +15,7 @@ 2. `POST /api/v1/risk-rules` را اجرا کنید. `Idempotency-Key` اختیاری و از نوع UUID است. برای retry امن یک UUID جدید برای هر عملیات منطقی تولید کنید؛ تکرار همان کلید با همان بدنه پاسخ 201 اولیه را برمی‌گرداند و بدنه یا کاربر متفاوت 409 می‌دهد. بدون کلید، تکرار POST یک قانون جدید می‌سازد. ```json -{"name":"Demo limit","type":"AMOUNT_LIMIT","parameters":{"max_amount_irr":100},"enabled":false} +{"name":"Demo limit","type":"AMOUNT_LIMIT","parameters":{"max_amount":100},"enabled":false} ``` شناسه `id` و `revision` پاسخ را نگه دارید. `effective_at` اختیاری است و اگر ارائه شود باید تاریخ و زمان معتبر باشد. @@ -23,7 +23,7 @@ 3. `PATCH /api/v1/risk-rules/{rule_id}` را با id و revision آخر اجرا کنید: ```json -{"expected_revision":1,"parameters":{"max_amount_irr":200}} +{"expected_revision":1,"parameters":{"max_amount":200}} ``` باید 200 و revision برابر ۲ دریافت کنید. حداقل یک فیلد قابل ویرایش لازم است؛ `type`، `actor` و `revision` قابل ارسال برای ویرایش نیستند. ارسال مجدد revision قدیمی باید 409 بدهد. @@ -40,16 +40,16 @@ $base = 'http://localhost:8084/api/v1' $headers = @{ Authorization = "Bearer $access" } $key = [guid]::NewGuid().ToString() $createHeaders = @{ Authorization = "Bearer $access"; 'Idempotency-Key' = $key } -$body = @{ name='Demo limit'; type='AMOUNT_LIMIT'; parameters=@{ max_amount_irr=100 }; enabled=$false } | ConvertTo-Json -Depth 5 +$body = @{ name='Demo limit'; type='AMOUNT_LIMIT'; parameters=@{ max_amount=100 }; enabled=$false } | ConvertTo-Json -Depth 5 $rule = Invoke-RestMethod -Method Post -Uri "$base/risk-rules" -Headers $createHeaders -ContentType 'application/json' -Body $body $id = $rule.id -$patch = @{ expected_revision=$rule.revision; parameters=@{ max_amount_irr=200 } } | ConvertTo-Json -Depth 5 +$patch = @{ expected_revision=$rule.revision; parameters=@{ max_amount=200 } } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Method Patch -Uri "$base/risk-rules/$id" -Headers $headers -ContentType 'application/json' -Body $patch Invoke-RestMethod -Method Get -Uri "$base/risk-rules/$id/audit" -Headers $headers ``` ## تست خودکار و migration -در ریشه، با `.venv` و تنظیمات اتصال به PostgreSQL آزمایشی: `python -m pytest --create-db`. تنظیمات پروژه `--reuse-db` دارد؛ پس از migration تازه `--create-db` دیتابیس **تست** را بازسازی می‌کند. هرگز آن را به دیتابیس غیرآزمایشی اشاره ندهید. از `s4_rsk` نیز `..\.venv\Scripts\python.exe -m pytest --create-db` قابل استفاده است. تست subprocess مربوط به manage.py عمداً پوشه `s4_rsk` را به‌عنوان working directory تنظیم می‌کند. +در PowerShell از ریشه پروژه `cd s4_rsk` و سپس `..\.venv\Scripts\python.exe -m pytest --create-db` را اجرا کنید. تنظیمات مشترک در `s4_rsk/pytest.ini` قرار دارد و `--reuse-db` فعال است؛ پس از migration تازه `--create-db` دیتابیس **تست** را بازسازی می‌کند. هرگز آن را به دیتابیس غیرآزمایشی اشاره ندهید. برای اجرا بدون تغییر پوشه از ریشه می‌توانید `.\.venv\Scripts\python.exe -m pytest -c s4_rsk/pytest.ini s4_rsk --create-db` را اجرا کنید. تست subprocess مربوط به manage.py عمداً پوشه `s4_rsk` را به‌عنوان working directory تنظیم می‌کند. تاریخچه تنها برای تغییرات مسیر سرویس تضمین می‌شود؛ تغییر مستقیم ORM/SQL قانون را دور می‌زند. trigger PostgreSQL از UPDATE و DELETE معمولی روی تاریخچه جلوگیری می‌کند اما از TRUNCATE یا غیرفعال‌کردن trigger توسط مالک جلوگیری نمی‌کند. در production دسترسی دیتابیس و فرآیند migration را تفکیک و محدود کنید. داده‌های قدیمی گذشته‌نگر بازسازی نشده‌اند. diff --git a/docs/test-matrices/us-02.md b/docs/test-matrices/us-02.md index a432de7..702e6e3 100644 --- a/docs/test-matrices/us-02.md +++ b/docs/test-matrices/us-02.md @@ -1,6 +1,6 @@ # ماتریس تست US-02: مدیریت قوانین ریسک -وضعیت: مبنای تست پیاده‌سازی حاضر. همه عملیات API به کاربر فعال در گروه `manager` نیاز دارند. `AMOUNT_LIMIT` نیازمند `max_amount_irr` صحیح بین ۱ و `2^63-1` است. هر نوشتن موفق از سرویس، revision و تاریخچه را در یک تراکنش ثبت می‌کند. +وضعیت: مبنای تست پیاده‌سازی حاضر. همه عملیات API به کاربر فعال در گروه `manager` نیاز دارند. `AMOUNT_LIMIT` نیازمند `max_amount` صحیح بین ۱ و `2^63-1` است. هر نوشتن موفق از سرویس، revision و تاریخچه را در یک تراکنش ثبت می‌کند. | شناسه | سناریو | ورودی | نتیجه مورد انتظار | پوشش | |---|---|---|---|---| diff --git a/docs/us-02b-rule-history.md b/docs/us-02b-rule-history.md index c3b149f..2b6ab01 100644 --- a/docs/us-02b-rule-history.md +++ b/docs/us-02b-rule-history.md @@ -1,7 +1,9 @@ # US-02B: Rule revision history -Manager-only POST, PATCH and audit endpoints use the transactional services in `rules.services`. They validate rule parameters, lock the rule during updates, reject stale revisions and record the actor and before/after snapshots atomically. Existing rules do not receive fabricated history: their first service update records the previous and new state. The `AMOUNT_LIMIT` parameter is `max_amount_irr` and must be an integer between 1 and the signed 64-bit maximum. `BLOCKLIST` currently accepts any object; more specific semantics need team agreement. +Manager-only POST, PATCH and audit endpoints use the transactional services in `rules.services`. They validate rule parameters, lock the rule during updates, reject stale revisions and record the actor and before/after snapshots atomically. Existing rules do not receive fabricated history: their first service update records the previous and new state. The `AMOUNT_LIMIT` parameter is `max_amount` and must be an integer between 1 and the signed 64-bit maximum. `BLOCKLIST` currently accepts any object; more specific semantics need team agreement. The PostgreSQL migration rejects ordinary UPDATE and DELETE statements on history rows. It does not restrict TRUNCATE or a database owner who disables the trigger. Direct ORM, bulk and SQL writes to `RiskRule` bypass service validation and history; production deployment needs separate, restricted database roles and an agreed way to enforce the service boundary. Database-owner privileges are not an audit protection boundary. -See [API testing](reports/us-02-api-testing.md) and the [test matrix](test-matrices/us-02.md). Tests run from the root or `s4_rsk`; after new migrations, `pytest --create-db` recreates the **test database**. Use a dedicated PostgreSQL instance and preserve important data. The subprocess test sets its working directory to `s4_rsk` so its relative `manage.py` path works from either directory. +The amount is expressed in IRR. Migration 0005 renames the legacy `max_amount_irr` key in current AMOUNT_LIMIT rules, retaining other parameters. If both keys exist with conflicting values, the migration stops for manual resolution. History snapshots and stored idempotent responses are intentionally not rewritten, so historical responses may still contain the old key. New requests must use `max_amount`. This data migration does not reverse the rename when rolled back. + +See [API testing](reports/us-02-api-testing.md) and the [test matrix](test-matrices/us-02.md). Run tests from `s4_rsk`, or from the repository root with `python -m pytest -c s4_rsk/pytest.ini s4_rsk`; after new migrations, `--create-db` recreates the **test database**. Use a dedicated PostgreSQL instance and preserve important data. The subprocess test sets its working directory to `s4_rsk` so its relative `manage.py` path works from either directory. diff --git a/frontend/src/api/schema.d.ts b/frontend/src/api/schema.d.ts index e0fcb6e..f78ceaa 100644 --- a/frontend/src/api/schema.d.ts +++ b/frontend/src/api/schema.d.ts @@ -580,6 +580,7 @@ export interface components { items: components["schemas"]["DecisionEvent"][]; next_cursor: string | null; }; + /** @description For AMOUNT_LIMIT, parameters.max_amount is a positive integer amount in IRR (maximum 9223372036854775807). */ RiskRuleInput: { name: string; /** @enum {string} */ @@ -592,6 +593,7 @@ export interface components { /** Format: date-time */ effective_at?: string; }; + /** @description For AMOUNT_LIMIT, parameters.max_amount is a positive integer amount in IRR (maximum 9223372036854775807). */ RiskRulePatch: { /** @description Revision the client last saw; a mismatch returns 409. */ expected_revision: number; @@ -1054,7 +1056,7 @@ export interface operations { * "name": "Max single transfer", * "type": "AMOUNT_LIMIT", * "parameters": { - * "max_amount_irr": 50000000 + * "max_amount": 50000000 * }, * "enabled": true, * "effective_at": "2026-10-01T00:00:00Z", diff --git a/openapi/s4_rsk.yaml b/openapi/s4_rsk.yaml index aaf7329..68f3357 100644 --- a/openapi/s4_rsk.yaml +++ b/openapi/s4_rsk.yaml @@ -282,7 +282,7 @@ paths: name: Max single transfer type: AMOUNT_LIMIT parameters: - max_amount_irr: 50000000 + max_amount: 50000000 enabled: true effective_at: '2026-10-01T00:00:00Z' revision: 1 @@ -964,6 +964,7 @@ components: type: [string, 'null'] RiskRuleInput: type: object + description: For AMOUNT_LIMIT, parameters.max_amount is a positive integer amount in IRR (maximum 9223372036854775807). required: [name, type, parameters] properties: name: @@ -984,6 +985,7 @@ components: format: date-time RiskRulePatch: type: object + description: For AMOUNT_LIMIT, parameters.max_amount is a positive integer amount in IRR (maximum 9223372036854775807). required: [expected_revision] properties: expected_revision: diff --git a/pytest.ini b/pytest.ini deleted file mode 100644 index a2d78ce..0000000 --- a/pytest.ini +++ /dev/null @@ -1,6 +0,0 @@ -[pytest] -DJANGO_SETTINGS_MODULE = config.settings -pythonpath = s4_rsk -testpaths = s4_rsk -python_files = tests.py test_*.py *_tests.py -addopts = --reuse-db -v diff --git a/s4_rsk/integration_testcontainers/risk_rules_cases.py b/s4_rsk/integration_testcontainers/risk_rules_cases.py index c8e1f8b..c1020f3 100644 --- a/s4_rsk/integration_testcontainers/risk_rules_cases.py +++ b/s4_rsk/integration_testcontainers/risk_rules_cases.py @@ -2,6 +2,7 @@ from django.contrib.auth.models import Group from django.db import connection from rest_framework.test import APIClient +from rest_framework_simplejwt.tokens import AccessToken from rules.models import RiskRule @@ -23,18 +24,14 @@ def test_manager_reads_rule_from_temporary_postgresql(django_user_model): rule = RiskRule.objects.create( name="Transfer amount limit", type=RiskRule.Type.AMOUNT_LIMIT, - parameters={"max_amount_irr": 5_000_000}, + parameters={"max_amount": 5_000_000}, enabled=False, revision=1, ) - # Logging in the user and requesting the list of rules. + # Authenticate with the same JWT mechanism used by the API. client = APIClient() - - assert client.login( - username="test-risk-manager", - password="test-only-password", - ) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(manager)}") response = client.get("/api/v1/risk-rules") @@ -48,7 +45,7 @@ def test_manager_reads_rule_from_temporary_postgresql(django_user_model): assert data["items"][0]["name"] == "Transfer amount limit" assert data["items"][0]["type"] == "AMOUNT_LIMIT" assert data["items"][0]["parameters"] == { - "max_amount_irr": 5_000_000 + "max_amount": 5_000_000 } assert data["items"][0]["enabled"] is False assert data["next_cursor"] is None @@ -75,10 +72,7 @@ def test_rule_list_caps_page_size_at_200(django_user_model): client = APIClient() - assert client.login( - username="pagination-manager", - password="test-only-password", - ) + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(manager)}") response = client.get( "/api/v1/risk-rules", diff --git a/s4_rsk/pytest.ini b/s4_rsk/pytest.ini index a75b67b..4167098 100644 --- a/s4_rsk/pytest.ini +++ b/s4_rsk/pytest.ini @@ -1,4 +1,5 @@ [pytest] DJANGO_SETTINGS_MODULE = config.settings +pythonpath = . python_files = tests.py test_*.py *_tests.py -addopts = --reuse-db -v \ No newline at end of file +addopts = --reuse-db -v diff --git a/s4_rsk/rules/fixtures/dev_risk_rules.json b/s4_rsk/rules/fixtures/dev_risk_rules.json index 8a66d37..17f11a6 100644 --- a/s4_rsk/rules/fixtures/dev_risk_rules.json +++ b/s4_rsk/rules/fixtures/dev_risk_rules.json @@ -5,7 +5,7 @@ "fields": { "name": "Development amount limit (disabled example)", "type": "AMOUNT_LIMIT", - "parameters": {"max_amount_irr": 100000000, "decision": "REVIEW"}, + "parameters": {"max_amount": 100000000, "decision": "REVIEW"}, "enabled": false, "effective_at": "2026-10-24T00:00:00Z", "revision": 1, diff --git a/s4_rsk/rules/migrations/0005_standardize_max_amount.py b/s4_rsk/rules/migrations/0005_standardize_max_amount.py new file mode 100644 index 0000000..14d5464 --- /dev/null +++ b/s4_rsk/rules/migrations/0005_standardize_max_amount.py @@ -0,0 +1,23 @@ +from django.db import migrations + + +def standardize_max_amount(apps, schema_editor): + RiskRule = apps.get_model("rules", "RiskRule") + for rule in RiskRule.objects.select_for_update().filter(type="AMOUNT_LIMIT").iterator(): + parameters = rule.parameters + if not isinstance(parameters, dict) or "max_amount_irr" not in parameters: + continue + old = parameters["max_amount_irr"] + if "max_amount" in parameters: + new = parameters["max_amount"] + if type(old) is not type(new) or old != new: + raise ValueError(f"Conflicting max_amount values in rule {rule.pk}; resolve before migration.") + else: + parameters["max_amount"] = old + del parameters["max_amount_irr"] + RiskRule.objects.filter(pk=rule.pk).update(parameters=parameters) + + +class Migration(migrations.Migration): + dependencies = [("rules", "0004_protect_rule_revision")] + operations = [migrations.RunPython(standardize_max_amount, migrations.RunPython.noop)] diff --git a/s4_rsk/rules/test_max_amount_migration.py b/s4_rsk/rules/test_max_amount_migration.py new file mode 100644 index 0000000..a064efe --- /dev/null +++ b/s4_rsk/rules/test_max_amount_migration.py @@ -0,0 +1,39 @@ +from importlib import import_module + +import pytest +from django.apps import apps +from django.db import transaction + +from .models import RiskRule + +migrate_values = import_module("rules.migrations.0005_standardize_max_amount").standardize_max_amount +pytestmark = pytest.mark.django_db + + +def test_legacy_rule_parameters_are_renamed(): + rule = RiskRule.objects.create( + name="legacy", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 100, "decision": "REVIEW"} + ) + migrate_values(apps, None) + rule.refresh_from_db() + assert rule.parameters == {"max_amount": 100, "decision": "REVIEW"} + + +def test_same_values_are_deduplicated(): + rule = RiskRule.objects.create( + name="legacy", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 100, "max_amount": 100} + ) + migrate_values(apps, None) + rule.refresh_from_db() + assert rule.parameters == {"max_amount": 100} + + +@pytest.mark.parametrize("new_value", [101, True]) +def test_conflicting_values_stop_migration_without_changes(new_value): + rule = RiskRule.objects.create( + name="conflict", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 1, "max_amount": new_value} + ) + with pytest.raises(ValueError, match="Conflicting"), transaction.atomic(): + migrate_values(apps, None) + rule.refresh_from_db() + assert rule.parameters == {"max_amount_irr": 1, "max_amount": new_value} diff --git a/s4_rsk/rules/test_rule_api.py b/s4_rsk/rules/test_rule_api.py index 2f46f8c..c58c2b5 100644 --- a/s4_rsk/rules/test_rule_api.py +++ b/s4_rsk/rules/test_rule_api.py @@ -25,7 +25,7 @@ def client_manager(django_user_model): @pytest.fixture def payload(): - return {"name": "limit", "type": "AMOUNT_LIMIT", "parameters": {"max_amount_irr": 100}} + return {"name": "limit", "type": "AMOUNT_LIMIT", "parameters": {"max_amount": 100}} def test_create_update_and_read_audit(client_manager, payload): @@ -35,15 +35,15 @@ def test_create_update_and_read_audit(client_manager, payload): rule_id = created.data["id"] assert created.data["revision"] == 1 changed = client.patch( - f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount_irr": 200}}, format="json" + f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount": 200}}, format="json" ) assert changed.status_code == 200 assert changed.data["revision"] == 2 history = client.get(f"{URL}/{rule_id}/audit").data["items"] assert [item["revision"] for item in history] == [2, 1] assert history[0]["actor"] == str(user.pk) - assert history[0]["before"]["parameters"] == {"max_amount_irr": 100} - assert history[0]["after"]["parameters"] == {"max_amount_irr": 200} + assert history[0]["before"]["parameters"] == {"max_amount": 100} + assert history[0]["after"]["parameters"] == {"max_amount": 200} assert history[1]["before"] is None @@ -71,7 +71,7 @@ def test_same_key_cannot_leak_response_to_another_manager(client_manager, payloa @pytest.mark.parametrize( "parameters", - [{}, {"max_amount_irr": 0}, {"max_amount_irr": -1}, {"max_amount_irr": True}, {"max_amount_irr": 2**63}, []], + [{}, {"max_amount": 0}, {"max_amount": -1}, {"max_amount": True}, {"max_amount": 2**63}, []], ) def test_invalid_parameters_rejected_without_side_effects(client_manager, payload, parameters): client, _ = client_manager @@ -87,7 +87,7 @@ def test_stale_and_invalid_patch_leave_original_unchanged(client_manager, payloa assert client.patch(f"{URL}/{rule_id}", {"expected_revision": 2, "name": "new"}, format="json").status_code == 409 assert ( client.patch( - f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount_irr": 0}}, format="json" + f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount": 0}}, format="json" ).status_code == 400 ) diff --git a/s4_rsk/rules/test_rule_history.py b/s4_rsk/rules/test_rule_history.py index b543ca2..f870a82 100644 --- a/s4_rsk/rules/test_rule_history.py +++ b/s4_rsk/rules/test_rule_history.py @@ -21,33 +21,33 @@ def manager(django_user_model): def test_create_and_update_record_before_after_and_actor(manager): - rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 100}) + rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount": 100}) created = rule.history.get(revision=1) assert created.before is None - assert created.after["parameters"] == {"max_amount_irr": 100} + assert created.after["parameters"] == {"max_amount": 100} assert created.actor == manager assert created.changed_at is not None - update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"parameters": {"max_amount_irr": 200}}) + update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"parameters": {"max_amount": 200}}) rule.refresh_from_db() updated = rule.history.get(revision=2) assert rule.revision == 2 - assert updated.before["parameters"] == {"max_amount_irr": 100} + assert updated.before["parameters"] == {"max_amount": 100} assert updated.before["revision"] == 1 - assert updated.after["parameters"] == {"max_amount_irr": 200} + assert updated.after["parameters"] == {"max_amount": 200} assert updated.after["revision"] == 2 - assert created.after["parameters"] == {"max_amount_irr": 100} + assert created.after["parameters"] == {"max_amount": 100} @pytest.mark.parametrize( "parameters", [ {}, - {"max_amount_irr": 0}, - {"max_amount_irr": -1}, - {"max_amount_irr": True}, - {"max_amount_irr": 1.5}, - {"max_amount_irr": 2**63}, + {"max_amount": 0}, + {"max_amount": -1}, + {"max_amount": True}, + {"max_amount": 1.5}, + {"max_amount": 2**63}, [], None, ], @@ -61,17 +61,17 @@ def test_invalid_amount_parameters_do_not_create_rule_or_history(manager, parame @pytest.mark.parametrize("amount", [1, 2**63 - 1]) def test_valid_amount_boundaries(manager, amount): - rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount_irr": amount}) + rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount": amount}) assert rule.history.count() == 1 def test_stale_revision_and_invalid_update_do_not_change_state(manager): - rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount_irr": 100}) + rule = create_rule(actor=manager, name="limit", type="AMOUNT_LIMIT", parameters={"max_amount": 100}) with pytest.raises(LabBankAPIException) as error: update_rule(actor=manager, rule_id=rule.pk, expected_revision=2, changes={"name": "changed"}) assert error.value.status_code == 409 with pytest.raises(ValidationError): - update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"parameters": {"max_amount_irr": 0}}) + update_rule(actor=manager, rule_id=rule.pk, expected_revision=1, changes={"parameters": {"max_amount": 0}}) rule.refresh_from_db() assert rule.revision == 1 assert rule.name == "limit" diff --git a/s4_rsk/rules/test_validators.py b/s4_rsk/rules/test_validators.py index 3294aed..1ffb531 100644 --- a/s4_rsk/rules/test_validators.py +++ b/s4_rsk/rules/test_validators.py @@ -6,11 +6,11 @@ @pytest.mark.parametrize("amount", [1, 2**63 - 1]) def test_valid_boundaries(amount): - validate_rule_parameters("AMOUNT_LIMIT", {"max_amount_irr": amount}) + validate_rule_parameters("AMOUNT_LIMIT", {"max_amount": amount}) -@pytest.mark.parametrize("parameters", [None, [], {}, {"max_amount_irr": 0}, - {"max_amount_irr": True}, {"max_amount_irr": 2**63}]) +@pytest.mark.parametrize("parameters", [None, [], {}, {"max_amount": 0}, + {"max_amount": True}, {"max_amount": 2**63}]) def test_invalid_validator_input(parameters): with pytest.raises(ValidationError): validate_rule_parameters("AMOUNT_LIMIT", parameters) @@ -18,3 +18,9 @@ def test_invalid_validator_input(parameters): def test_blocklist_accepts_empty_object(): validate_rule_parameters("BLOCKLIST", {}) + + +@pytest.mark.parametrize("parameters", [{"max_amount_irr": 1}, {"max_amount": 1, "max_amount_irr": 1}]) +def test_old_field_name_is_rejected(parameters): + with pytest.raises(ValidationError): + validate_rule_parameters("AMOUNT_LIMIT", parameters) diff --git a/s4_rsk/rules/tests.py b/s4_rsk/rules/tests.py index 029afab..22353cc 100644 --- a/s4_rsk/rules/tests.py +++ b/s4_rsk/rules/tests.py @@ -41,7 +41,7 @@ def make_rule(**kwargs): def test_manager_reads_stored_configuration(manager_client): - rule = make_rule(parameters={"max_amount_irr": 5000000}, enabled=False, revision=2) + rule = make_rule(parameters={"max_amount": 5000000}, enabled=False, revision=2) response = manager_client.get(URL, HTTP_X_CORRELATION_ID="rules-list-test") assert response.status_code == 200 assert response["X-Correlation-ID"] == "rules-list-test" @@ -51,7 +51,7 @@ def test_manager_reads_stored_configuration(manager_client): "id": str(rule.id), "name": rule.name, "type": "AMOUNT_LIMIT", - "parameters": {"max_amount_irr": 5000000}, + "parameters": {"max_amount": 5000000}, "enabled": False, "revision": 2, "effective_at": rule.effective_at.isoformat().replace("+00:00", "Z"), diff --git a/s4_rsk/rules/validators.py b/s4_rsk/rules/validators.py index f83c3ae..362fe82 100644 --- a/s4_rsk/rules/validators.py +++ b/s4_rsk/rules/validators.py @@ -6,6 +6,8 @@ def validate_rule_parameters(rule_type, parameters): if not isinstance(parameters, dict): raise ValidationError({"parameters": "Parameters must be a JSON object."}) if rule_type == "AMOUNT_LIMIT": - amount = parameters.get("max_amount_irr") + if "max_amount_irr" in parameters: + raise ValidationError({"parameters": "Use max_amount; max_amount_irr is no longer accepted."}) + amount = parameters.get("max_amount") if isinstance(amount, bool) or not isinstance(amount, int) or not 1 <= amount <= 2**63 - 1: - raise ValidationError({"parameters": "max_amount_irr must be a positive signed 64-bit integer."}) + raise ValidationError({"parameters": "max_amount must be a positive signed 64-bit integer."}) From a77234da2f25b263bbaa79dbe4c8423e8866fcd9 Mon Sep 17 00:00:00 2001 From: AliJohari05 Date: Sat, 7 Nov 2026 18:04:59 +0330 Subject: [PATCH 5/6] fix(rules): return idempotency reuse error code --- docs/reports/us-02-api-testing.md | 2 +- docs/test-matrices/us-02.md | 2 +- frontend/src/api/schema.d.ts | 5 ++++- openapi/s4_rsk.yaml | 1 + s4_rsk/rules/test_rule_api.py | 20 ++++++++++++++++++-- s4_rsk/rules/tests.py | 3 --- s4_rsk/rules/views.py | 6 +++--- 7 files changed, 28 insertions(+), 11 deletions(-) diff --git a/docs/reports/us-02-api-testing.md b/docs/reports/us-02-api-testing.md index 70e2caa..819bd1e 100644 --- a/docs/reports/us-02-api-testing.md +++ b/docs/reports/us-02-api-testing.md @@ -12,7 +12,7 @@ ## گردش آزمون در Swagger 1. `GET /api/v1/risk-rules` را با Try it out و Execute اجرا کنید. پاسخ 200 و `items` و `next_cursor` است. `limit` اندازه صفحه است و `cursor` پاسخ قبلی را برای صفحه بعد می‌دهید. -2. `POST /api/v1/risk-rules` را اجرا کنید. `Idempotency-Key` اختیاری و از نوع UUID است. برای retry امن یک UUID جدید برای هر عملیات منطقی تولید کنید؛ تکرار همان کلید با همان بدنه پاسخ 201 اولیه را برمی‌گرداند و بدنه یا کاربر متفاوت 409 می‌دهد. بدون کلید، تکرار POST یک قانون جدید می‌سازد. +2. `POST /api/v1/risk-rules` را اجرا کنید. `Idempotency-Key` اختیاری و از نوع UUID است. برای retry امن یک UUID جدید برای هر عملیات منطقی تولید کنید؛ تکرار همان کلید با همان بدنه پاسخ 201 اولیه را برمی‌گرداند و بدنه یا کاربر متفاوت 409 با کد `IDEMPOTENCY_KEY_REUSED` می‌دهد. بدون کلید، تکرار POST یک قانون جدید می‌سازد. ```json {"name":"Demo limit","type":"AMOUNT_LIMIT","parameters":{"max_amount":100},"enabled":false} diff --git a/docs/test-matrices/us-02.md b/docs/test-matrices/us-02.md index 702e6e3..29a2299 100644 --- a/docs/test-matrices/us-02.md +++ b/docs/test-matrices/us-02.md @@ -11,7 +11,7 @@ | R02-05 | رقابت کاربران | expected_revision قدیمی | 409 بدون تغییر یا تاریخچه تازه | `test_stale_and_invalid_patch_leave_original_unchanged` | | R02-06 | اصلاح نامعتبر | مقدار نامعتبر یا actor در بدنه | 400؛ وضعیت ثابت می‌ماند | همان تست R02-05 | | R02-07 | retry درخواست ایجاد | کلید و بدنه یکسان | همان 201 و همان پاسخ؛ فقط یک قانون و تاریخچه | `test_post_replay_and_conflict` | -| R02-08 | استفاده مجدد از کلید | همان کلید با بدنه یا کاربر متفاوت | 409 و افشاشدن پاسخ قبلی رخ نمی‌دهد | `test_post_replay_and_conflict`, `test_same_key_cannot_leak_response_to_another_manager` | +| R02-08 | استفاده مجدد از کلید | همان کلید با بدنه یا کاربر متفاوت | 409 با کد `IDEMPOTENCY_KEY_REUSED`؛ پاسخ قبلی افشا نمی‌شود | `test_post_replay_and_conflict`, `test_same_key_cannot_leak_response_to_another_manager` | | R02-09 | احراز هویت و دسترسی | بدون JWT یا بدون گروه manager | به‌ترتیب 401 و 403 | `test_auth_and_missing_rule`, `test_non_managers_are_denied` | | R02-10 | قانون ناموجود | UUID ناشناخته | 404 برای ویرایش و تاریخچه | `test_auth_and_missing_rule` | | R02-11 | صفحه‌بندی تاریخچه | limit=1 و cursor | نسخه‌ها به‌ترتیب نزولی بدون تکرار | `test_audit_cursor_pages` | diff --git a/frontend/src/api/schema.d.ts b/frontend/src/api/schema.d.ts index f78ceaa..20fd0bb 100644 --- a/frontend/src/api/schema.d.ts +++ b/frontend/src/api/schema.d.ts @@ -240,7 +240,10 @@ export interface paths { */ get: operations["risk_rules_list"]; put?: never; - /** Create a risk rule */ + /** + * Create a risk rule + * @description Reusing an Idempotency-Key with a different body returns 409 with code `IDEMPOTENCY_KEY_REUSED`. + */ post: operations["createRiskRule"]; delete?: never; options?: never; diff --git a/openapi/s4_rsk.yaml b/openapi/s4_rsk.yaml index 68f3357..68ad022 100644 --- a/openapi/s4_rsk.yaml +++ b/openapi/s4_rsk.yaml @@ -299,6 +299,7 @@ paths: security: - bearerAuth: [] summary: Create a risk rule + description: Reusing an Idempotency-Key with a different body returns 409 with code `IDEMPOTENCY_KEY_REUSED`. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: diff --git a/s4_rsk/rules/test_rule_api.py b/s4_rsk/rules/test_rule_api.py index c58c2b5..3199112 100644 --- a/s4_rsk/rules/test_rule_api.py +++ b/s4_rsk/rules/test_rule_api.py @@ -56,6 +56,11 @@ def test_post_replay_and_conflict(client_manager, payload): assert first.data == replay.data conflict = client.post(URL, {**payload, "name": "different"}, format="json", HTTP_IDEMPOTENCY_KEY=key) assert conflict.status_code == 409 + assert conflict.data["code"] == "IDEMPOTENCY_KEY_REUSED" + assert conflict["Content-Type"] == "application/problem+json" + invalid_body = client.post(URL, {}, format="json", HTTP_IDEMPOTENCY_KEY=key) + assert invalid_body.status_code == 409 + assert invalid_body.data["code"] == "IDEMPOTENCY_KEY_REUSED" assert RiskRule.objects.count() == RuleRevision.objects.count() == 1 @@ -66,7 +71,16 @@ def test_same_key_cannot_leak_response_to_another_manager(client_manager, payloa other = django_user_model.objects.create_user("other-manager") other.groups.add(Group.objects.get(name="manager")) client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(other)}") - assert client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key).status_code == 409 + response = client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key) + assert response.status_code == 409 + assert response.data["code"] == "IDEMPOTENCY_KEY_REUSED" + + +def test_invalid_first_request_does_not_consume_idempotency_key(client_manager, payload): + client, _ = client_manager + key = str(uuid.uuid4()) + assert client.post(URL, {}, format="json", HTTP_IDEMPOTENCY_KEY=key).status_code == 400 + assert client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key).status_code == 201 @pytest.mark.parametrize( @@ -84,7 +98,9 @@ def test_invalid_parameters_rejected_without_side_effects(client_manager, payloa def test_stale_and_invalid_patch_leave_original_unchanged(client_manager, payload): client, _ = client_manager rule_id = client.post(URL, payload, format="json").data["id"] - assert client.patch(f"{URL}/{rule_id}", {"expected_revision": 2, "name": "new"}, format="json").status_code == 409 + stale = client.patch(f"{URL}/{rule_id}", {"expected_revision": 2, "name": "new"}, format="json") + assert stale.status_code == 409 + assert stale.data["code"] == "CONFLICT" assert ( client.patch( f"{URL}/{rule_id}", {"expected_revision": 1, "parameters": {"max_amount": 0}}, format="json" diff --git a/s4_rsk/rules/tests.py b/s4_rsk/rules/tests.py index 16dfaa3..22353cc 100644 --- a/s4_rsk/rules/tests.py +++ b/s4_rsk/rules/tests.py @@ -143,9 +143,6 @@ def test_bad_cursor_returns_problem_details(manager_client): def test_invalid_create_is_rejected(manager_client): response = manager_client.post(URL, {}, format="json") assert response.status_code == 400 -def test_authenticated_unsafe_requests_are_not_allowed(manager_client): - response = manager_client.post(URL, {}, format="json") - assert response.status_code == 405 assert RiskRule.objects.count() == 0 diff --git a/s4_rsk/rules/views.py b/s4_rsk/rules/views.py index fa8b082..9ecf436 100644 --- a/s4_rsk/rules/views.py +++ b/s4_rsk/rules/views.py @@ -59,8 +59,6 @@ def get(self, request, *args, **kwargs): responses={201: RiskRuleSerializer, 400: ProblemSerializer, 409: ProblemSerializer}, ) def post(self, request): - serializer = RiskRuleInputSerializer(data=request.data) - serializer.is_valid(raise_exception=True) key = request.headers.get("Idempotency-Key") if key is not None: try: @@ -80,9 +78,11 @@ def post(self, request): if not created: if record.actor_id != request.user.pk or record.fingerprint != fingerprint: raise LabBankAPIException( - "CONFLICT", "Conflict", "Idempotency key already used.", 409, "conflict" + "IDEMPOTENCY_KEY_REUSED", "Conflict", "Idempotency key already used.", 409, "conflict" ) return Response(record.response, status=status.HTTP_201_CREATED) + serializer = RiskRuleInputSerializer(data=request.data) + serializer.is_valid(raise_exception=True) rule = create_rule(actor=request.user, **serializer.validated_data) data = dict(RiskRuleSerializer(rule).data) if record is not None: From f2797c9621cd3a019084ef9071716760d931deb6 Mon Sep 17 00:00:00 2001 From: AliJohari05 Date: Sun, 8 Nov 2026 21:56:21 +0330 Subject: [PATCH 6/6] test: add lab 5 API and consumer contract coverage --- docs/reports/lab5-additions.md | 31 +++ docs/test-matrices/README.md | 2 + docs/test-matrices/frontend.md | 15 ++ docs/test-matrices/ledger-consumer.md | 23 +++ frontend/package.json | 2 +- frontend/src/App.extra.test.tsx | 110 +++++++++++ frontend/src/api/schema.d.ts | 13 ++ openapi/neighbors/s2_ldg.yaml | 117 +++++++++++ openapi/s4_rsk.yaml | 16 ++ s4_rsk/common/openapi_contract.py | 124 ++++++++++++ s4_rsk/common/test_health_contract.py | 33 ++++ s4_rsk/conftest.py | 17 ++ s4_rsk/integrations/__init__.py | 0 s4_rsk/integrations/ledger_client.py | 168 ++++++++++++++++ .../integrations/test_ledger_client_stub.py | 184 ++++++++++++++++++ s4_rsk/integrations/test_ledger_contract.py | 66 +++++++ s4_rsk/pytest.ini | 3 + s4_rsk/rules/test_rule_contract.py | 132 +++++++++++++ 18 files changed, 1055 insertions(+), 1 deletion(-) create mode 100644 docs/reports/lab5-additions.md create mode 100644 docs/test-matrices/frontend.md create mode 100644 docs/test-matrices/ledger-consumer.md create mode 100644 frontend/src/App.extra.test.tsx create mode 100644 openapi/neighbors/s2_ldg.yaml create mode 100644 s4_rsk/common/openapi_contract.py create mode 100644 s4_rsk/common/test_health_contract.py create mode 100644 s4_rsk/conftest.py create mode 100644 s4_rsk/integrations/__init__.py create mode 100644 s4_rsk/integrations/ledger_client.py create mode 100644 s4_rsk/integrations/test_ledger_client_stub.py create mode 100644 s4_rsk/integrations/test_ledger_contract.py create mode 100644 s4_rsk/rules/test_rule_contract.py diff --git a/docs/reports/lab5-additions.md b/docs/reports/lab5-additions.md new file mode 100644 index 0000000..caa4b80 --- /dev/null +++ b/docs/reports/lab5-additions.md @@ -0,0 +1,31 @@ +# تغییرات آزمایش ۵ و اجرای تست‌ها + +در این محیط ویندوز، برای اتصال مستقیم به PostgreSQL از `127.0.0.1` استفاده کنید؛ `localhost` ممکن است در اتصال معطل بماند. برای پرهیز از استفاده از دیتابیس تست قدیمی با migrationهای ناسازگار، در PowerShell قبل از اجرای pytest مقدارهای زیر را تنظیم کنید: + +```powershell +$env:POSTGRES_HOST = '127.0.0.1' +$env:POSTGRES_DB = 'lab5_verify_20261108' +``` + +pytest یک دیتابیس آزمایشی به نام `test_lab5_verify_20261108` می‌سازد؛ استفاده از `--create-db` دیتابیس آزمایشی هم‌نام را بازسازی می‌کند. تست‌های همسایه فقط با گزینهٔ `--run-neighbor-contract` اجرا می‌شوند. نتیجهٔ Prism بر اساس پیش‌نویس، تأیید سرویس واقعی S2 نیست. + +آزمون‌های تطابق پاسخ APIهای قوانین و health با `openapi/s4_rsk.yaml` در گروه `openapi` قرار دارند. برای اجرای تمام تست‌های بک‌اند از ریشه در PowerShell، با PostgreSQL آزمایشی آماده: + +```powershell +cd s4_rsk +..\.venv\Scripts\python.exe -m pytest --create-db +``` + +بعد از اعمال migration جدید، `--create-db` دیتابیس **تست** را بازسازی می‌کند. در دفعات بعد می‌توانید این گزینه را حذف کنید. برای اجرای تست‌های قرارداد سرویس خودمان از همین پوشه `..\.venv\Scripts\python.exe -m pytest -m openapi` را اجرا کنید. + +در فرانت‌اند `cd frontend`، سپس `npm ci` و `npm test` را اجرا کنید. تست‌ها از Vitest و React Testing Library استفاده می‌کنند و درخواست واقعی به بک‌اند نمی‌فرستند. + +## دفترکل S2 + +`openapi/neighbors/s2_ldg.yaml` فقط **پیش‌نویس فرضی** است و قرارداد تأییدشدهٔ تیم S2 نیست. کلاینت دفترکل و تست‌های MockTransport آماده بررسی‌اند، اما به ارزیابی واقعی تراکنش وصل نشده‌اند. برای اتصال واقعی باید قرارداد و نحوهٔ احراز هویت با تیم S2 توافق و بعد پیاده‌سازی و تست شود. + +تست‌های `contract` به‌طور پیش‌فرض اجرا نمی‌شوند. پس از آماده‌کردن Prism یا سرویس آزمایشی و جایگزینی قرارداد تأییدشده، آدرس مورد اعتماد را در `NEIGHBOR_BASE_URL` تنظیم کنید و از `s4_rsk` با `..\.venv\Scripts\python.exe -m pytest -m contract --run-neighbor-contract` اجرا کنید. این دستور به سرویس مشخص‌شده درخواست واقعی می‌فرستد. برای حساب‌های آزمایشی از `NEIGHBOR_ACCOUNT_ID_OK` و `NEIGHBOR_ACCOUNT_ID_MISSING` استفاده کنید. + +برای تمرین با همین پیش‌نویس، از ریشه `prism mock openapi/neighbors/s2_ldg.yaml -p 4010` را اجرا کنید. در ترمینال دوم و پوشهٔ `s4_rsk` مقدار `$env:NEIGHBOR_BASE_URL='http://127.0.0.1:4010'` را تنظیم کنید و دستور تست بالا را اجرا کنید. پاسخ ۴۰۴ در این آزمون با هدر مخصوص Prism شبیه‌سازی می‌شود؛ موفقیت در Prism به معنی تأیید سرویس واقعی نیست. + +اسکریپت نمونهٔ ساخت کاربر و seed خودکار بسته ادغام نشده است: نسخهٔ پیشنهادی می‌تواند حساب موجود را فعال کند، رمز آن را تغییر دهد یا fixture را مجدداً بارگذاری کند. برای ساخت کاربر به [راهنمای JWT](jwt-authentication.md) مراجعه کنید. diff --git a/docs/test-matrices/README.md b/docs/test-matrices/README.md index 7be8999..4b4e4c2 100644 --- a/docs/test-matrices/README.md +++ b/docs/test-matrices/README.md @@ -12,3 +12,5 @@ - [US-02 مدیریت قوانین](us-02.md) - [US-08 توضیح‌پذیری تصمیم، پیش‌نویس](us-08-draft.md) +- [تست‌های فرانت‌اند](frontend.md) +- [پیش‌نویس تست مصرف‌کننده دفترکل](ledger-consumer.md) diff --git a/docs/test-matrices/frontend.md b/docs/test-matrices/frontend.md new file mode 100644 index 0000000..ce12249 --- /dev/null +++ b/docs/test-matrices/frontend.md @@ -0,0 +1,15 @@ +# ماتریس تست فرانت‌اند (Component Test با Vitest و React Testing Library) + +| شناسه | سناریو | ورودی (fetch ساختگی) | نتیجهٔ مورد انتظار | Edge | تست | +|---|---|---|---|---|---| +| F-01 | سلامت موفق | 200 با `{status: UP}` | پیام «بک‌اند در دسترس است» و JSON سرویس | خیر | `با پاسخ ۲۰۰ بک‌اند، پیام موفقیت را نشان می‌دهد` | +| F-02 | خطای شبکه | `fetch` رد می‌شود | «خطا: Failed to fetch» | بله | `اگر بک‌اند خطا بدهد، پیام خطا را نشان می‌دهد` | +| F-03 | مسیر ناشناخته | آدرس `/abc` | صفحهٔ ۴۰۴ | بله | `آدرس ناشناخته صفحه‌ی ۴۰۴ را نشان می‌دهد` | +| F-04 | Problem Details | 503 با `application/problem+json` | عنوان، کد، توضیح و `correlation_id` نمایش داده می‌شود | بله | `خطای Problem Details را با کد و شناسهٔ ردیابی نشان می‌دهد` | +| F-05 | خطای HTTP بدون Problem Details | 500 با متن ساده | پیام کلی «HTTP 500» بدون جزئیات ساختگی | بله | `خطای HTTP عادی را بدون جزئیات Problem نشان می‌دهد` | +| F-06 | تلاش دوباره | کلیک روی «بررسی دوباره» | `fetch` دوباره صدا زده می‌شود | خیر | `کلیک روی بررسی دوباره درخواست تازه می‌فرستد` | + +## پوشش‌نیافته‌ها + +- فرم و فهرست قوانین (US-02C): هنوز پیاده‌سازی نشده‌اند؛ تست‌های کامپوننتشان همراه همان استوری در اسپرینت ۴ می‌آید. +- تست E2E با Playwright: در جلسهٔ ۵ لازم نیست؛ فقط ابزار نصب شده است. diff --git a/docs/test-matrices/ledger-consumer.md b/docs/test-matrices/ledger-consumer.md new file mode 100644 index 0000000..9acbfc9 --- /dev/null +++ b/docs/test-matrices/ledger-consumer.md @@ -0,0 +1,23 @@ +# ماتریس تست مصرف‌کننده: کلاینت دفترکل S2-LDG + +وضعیت: کلاینت `s4_rsk/integrations/ledger_client.py` آزمون شده است ولی هنوز در `assessments.services` فراخوانی نمی‌شود (US-01B). پاسخ‌های Stub از مثال‌های `openapi/neighbors/s2_ldg.yaml` گرفته شده‌اند. اگر فایل واقعی S2 جایگزین شد، تست‌ها دوباره اجرا شوند. + +| شناسه | سناریو | پاسخ Stub / ورودی | نتیجهٔ مورد انتظار | Edge | تست خودکار | +|---|---|---|---|---|---| +| L-01 | پاسخ موفق | 200 با دو بدهکاری | دو ورودی تجزیه‌شده، وضعیت OK، بدون تصمیم اجباری؛ درخواست شامل `direction=DEBIT`، `from` و `X-Correlation-ID` | خیر | `test_success_returns_parsed_debits_and_sends_the_draft_request` | +| L-02 | صفحه‌بندی | صفحهٔ اول با `next_cursor` | درخواست دوم با همان cursor و ادغام نتایج | بله | `test_pagination_follows_next_cursor_until_exhausted` | +| L-03 | حساب ناموجود | 404 Problem Details | `ACCOUNT_NOT_FOUND` و تصمیم اجباری REVIEW | بله | `test_unknown_account_forces_review_with_explicit_reason` | +| L-04 | Timeout | استثنای `ConnectTimeout` | `LEDGER_UNAVAILABLE` و REVIEW بدون پرتاب خطا | بله | `test_timeout_forces_review_instead_of_raising` | +| L-05 | خطای سرور | 503 Problem Details | `LEDGER_UNAVAILABLE` و REVIEW | بله | `test_server_error_forces_review` | +| L-06 | بدنهٔ ناقص | 200 بدون فیلد `amount` | خطا، نه اعتماد به داده؛ REVIEW | بله | `test_malformed_success_body_is_not_trusted` | +| L-07 | آدرس همسایه | `NEIGHBOR_BASE_URL` | درخواست به همان میزبان و پورت می‌رود | خیر | `test_neighbor_base_url_environment_variable_selects_the_host` | +| L-08 | آدرس تنظیم‌نشده | بدون متغیر محیطی | خطای روشن، نه آدرس حدسی | بله | `test_missing_neighbor_base_url_is_a_clear_error` | +| L-09 | خطای غیرمنتظرهٔ ۴xx | 403 | خطا، نه تاریخچهٔ خالی؛ تصمیم اجباری REVIEW | بله | `test_unexpected_client_error_is_not_treated_as_empty_history` | +| L-10 | زنجیرهٔ بی‌پایان cursor | هر صفحه `next_cursor` دارد | قطع پس از سقف صفحه‌ها با خطا | بله | `test_endless_cursor_chain_is_cut_off` | +| L-11 | توکن سرویس | کلاینت با `token` | هدر `Authorization: Bearer` ارسال می‌شود | خیر | `test_bearer_token_is_sent_when_configured` | +| L-12 | Contract Test روی Prism یا همسایهٔ واقعی | `NEIGHBOR_BASE_URL` | موفق و خطا با قرارداد همسایه می‌خوانند | خیر | `test_ledger_contract.py` (نشانگر `contract`) | + +## پوشش‌نیافته‌ها + +- احراز هویت سرویس‌به‌سرویس به S2: روش آن هنوز با تیم S2 توافق نشده؛ فقط ارسال هدر آزموده شده (L-11)، نه پذیرفته‌شدن توسط S2. +- retry با backoff: عمداً پیاده‌سازی نشده است؛ هر خطا یک سیگنال REVIEW است (طبق نمودار توالی جلسهٔ ۴). diff --git a/frontend/package.json b/frontend/package.json index 133d7bb..a0ad6fc 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -19,9 +19,9 @@ }, "devDependencies": { "@playwright/test": "^1.64.1", + "@testing-library/dom": "^10.4.2", "@testing-library/jest-dom": "^7.0.1", "@testing-library/react": "^16.3.3", - "@testing-library/dom": "^10.4.2", "@types/node": "^24.19.2", "@types/react": "^19.3.0", "@types/react-dom": "^19.3.0", diff --git a/frontend/src/App.extra.test.tsx b/frontend/src/App.extra.test.tsx new file mode 100644 index 0000000..a6fd5cc --- /dev/null +++ b/frontend/src/App.extra.test.tsx @@ -0,0 +1,110 @@ +import { cleanup, fireEvent, render, screen } from '@testing-library/react' +import { afterEach, describe, expect, it, vi } from 'vitest' +import App from './App' + +afterEach(() => { + cleanup() + vi.unstubAllGlobals() + window.history.replaceState(null, '', '/') +}) + +describe('صفحه‌ی /health', () => { + it('با پاسخ ۲۰۰ بک‌اند، پیام موفقیت را نشان می‌دهد', async () => { + window.history.replaceState(null, '', '/health') + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue({ + ok: true, + status: 200, + json: async () => ({ status: 'UP', service: 's4-rsk' }), + }), + ) + + render() + + expect(await screen.findByText(/بک‌اند در دسترس است/)).toBeInTheDocument() + expect(screen.getByText(/"service": "s4-rsk"/)).toBeInTheDocument() + }) + + it('اگر بک‌اند خطا بدهد، پیام خطا را نشان می‌دهد', async () => { + window.history.replaceState(null, '', '/health') + vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('Failed to fetch'))) + + render() + + expect(await screen.findByText(/خطا: Failed to fetch/)).toBeInTheDocument() + }) + + it('آدرس ناشناخته صفحه‌ی ۴۰۴ را نشان می‌دهد', () => { + window.history.replaceState(null, '', '/abc') + + render() + + expect(screen.getByText('۴۰۴')).toBeInTheDocument() + }) + + it('خطای Problem Details را با کد و شناسهٔ ردیابی نشان می‌دهد', async () => { + window.history.replaceState(null, '', '/health') + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue({ + ok: false, + status: 503, + headers: new Headers({ 'content-type': 'application/problem+json' }), + json: async () => ({ + type: 'https://errors.labbank.example/service-unavailable', + title: 'Dependency unavailable', + status: 503, + code: 'SERVICE_UNAVAILABLE', + detail: 'The database is unavailable.', + correlation_id: 'cid-503', + }), + }), + ) + + render() + + expect(await screen.findByRole('alert')).toHaveTextContent('Dependency unavailable') + const details = screen.getByRole('alert') + expect(details).toHaveTextContent('SERVICE_UNAVAILABLE') + expect(details).toHaveTextContent('The database is unavailable.') + expect(details).toHaveTextContent('cid-503') + }) + + it('خطای HTTP عادی را بدون جزئیات Problem نشان می‌دهد', async () => { + window.history.replaceState(null, '', '/health') + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue({ + ok: false, + status: 500, + headers: new Headers({ 'content-type': 'text/html' }), + json: async () => { + throw new Error('not json') + }, + }), + ) + + render() + + expect(await screen.findByText(/خطا: HTTP 500/)).toBeInTheDocument() + expect(screen.queryByRole('alert')).not.toBeInTheDocument() + }) + + it('کلیک روی بررسی دوباره درخواست تازه می‌فرستد', async () => { + window.history.replaceState(null, '', '/health') + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + status: 200, + json: async () => ({ status: 'UP', service: 's4-rsk' }), + }) + vi.stubGlobal('fetch', fetchMock) + + render() + await screen.findByText(/بک‌اند در دسترس است/) + fireEvent.click(screen.getByRole('button', { name: 'بررسی دوباره' })) + + await screen.findByText(/بک‌اند در دسترس است/) + expect(fetchMock).toHaveBeenCalledTimes(2) + }) +}) diff --git a/frontend/src/api/schema.d.ts b/frontend/src/api/schema.d.ts index 20fd0bb..d38d82d 100644 --- a/frontend/src/api/schema.d.ts +++ b/frontend/src/api/schema.d.ts @@ -760,6 +760,15 @@ export interface components { "application/problem+json": components["schemas"]["Problem"]; }; }; + /** @description The access token is missing, invalid or expired. */ + Unauthorized: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; /** @description The authenticated caller lacks the required role (`FORBIDDEN`). */ Forbidden: { headers: { @@ -1074,6 +1083,7 @@ export interface operations { "application/json": components["schemas"]["RiskRulePage"]; }; }; + 401: components["responses"]["Unauthorized"]; 403: components["responses"]["Forbidden"]; 404: components["responses"]["NotFound"]; }; @@ -1104,6 +1114,7 @@ export interface operations { }; }; 400: components["responses"]["BadRequest"]; + 401: components["responses"]["Unauthorized"]; 403: components["responses"]["Forbidden"]; 409: components["responses"]["Conflict"]; }; @@ -1133,6 +1144,7 @@ export interface operations { }; }; 400: components["responses"]["BadRequest"]; + 401: components["responses"]["Unauthorized"]; 403: components["responses"]["Forbidden"]; 404: components["responses"]["NotFound"]; 409: components["responses"]["Conflict"]; @@ -1163,6 +1175,7 @@ export interface operations { "application/json": components["schemas"]["RuleRevisionPage"]; }; }; + 401: components["responses"]["Unauthorized"]; 403: components["responses"]["Forbidden"]; 404: components["responses"]["NotFound"]; }; diff --git a/openapi/neighbors/s2_ldg.yaml b/openapi/neighbors/s2_ldg.yaml new file mode 100644 index 0000000..f8067c5 --- /dev/null +++ b/openapi/neighbors/s2_ldg.yaml @@ -0,0 +1,117 @@ +# DRAFT of the S2-LDG endpoint that S4-RSK consumes. +# +# The field names below were derived from our own contract (openapi/s4_rsk.yaml, +# "source_account_id") and the session-4 sequence diagram. They are an ASSUMPTION. +# Replace this file with the real contract copied from the S2-LDG team's repository +# (same path), then re-run the stub and contract tests; fix LedgerEntry and the +# test data only where the real names differ. +openapi: 3.1.0 +info: + title: S2-LDG ledger (consumer-side copy, draft) + version: 0.1.0-draft +servers: + - url: http://localhost:8082 +paths: + /api/v1/accounts/{account_id}/entries: + get: + operationId: listAccountEntries + summary: Ledger entries of one account, newest first + parameters: + - name: account_id + in: path + required: true + schema: { type: string, format: uuid } + - name: direction + in: query + required: false + schema: { type: string, enum: [DEBIT, CREDIT] } + - name: from + in: query + required: false + schema: { type: string, format: date-time } + - name: limit + in: query + required: false + schema: { type: integer, minimum: 1, maximum: 200 } + - name: cursor + in: query + required: false + schema: { type: string } + responses: + '200': + description: A page of entries. + content: + application/json: + schema: + $ref: '#/components/schemas/EntryPage' + example: + items: + - id: 0192f5a0-1111-7000-8000-000000000001 + account_id: 0192f5a0-5555-7aaa-8bbb-0123456789ab + direction: DEBIT + amount: 1500000 + currency: IRR + occurred_at: '2026-10-24T08:00:00Z' + - id: 0192f5a0-1111-7000-8000-000000000002 + account_id: 0192f5a0-5555-7aaa-8bbb-0123456789ab + direction: DEBIT + amount: 700000 + currency: IRR + occurred_at: '2026-10-24T08:10:00Z' + next_cursor: null + '404': + description: The account does not exist (`NOT_FOUND`). + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://errors.labbank.example/not-found + title: Resource not found + status: 404 + code: NOT_FOUND + detail: Account was not found. + correlation_id: 7f3c1e52-5a0b-4a4f-9c1e-0d2b6a9f1c33 + '503': + description: The ledger is temporarily unavailable. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://errors.labbank.example/service-unavailable + title: Dependency unavailable + status: 503 + code: SERVICE_UNAVAILABLE + detail: The ledger database is unavailable. + correlation_id: 7f3c1e52-5a0b-4a4f-9c1e-0d2b6a9f1c33 +components: + schemas: + Entry: + type: object + required: [id, account_id, direction, amount, occurred_at] + properties: + id: { type: string, format: uuid } + account_id: { type: string, format: uuid } + direction: { type: string, enum: [DEBIT, CREDIT] } + amount: { type: integer, minimum: 1 } + currency: { type: string, enum: [IRR] } + occurred_at: { type: string, format: date-time } + EntryPage: + type: object + required: [items, next_cursor] + properties: + items: + type: array + items: { $ref: '#/components/schemas/Entry' } + next_cursor: { type: [string, 'null'] } + Problem: + type: object + required: [type, title, status, code, detail, correlation_id] + properties: + type: { type: string } + title: { type: string } + status: { type: integer } + code: { type: string } + detail: { type: string } + correlation_id: { type: string } diff --git a/openapi/s4_rsk.yaml b/openapi/s4_rsk.yaml index 68ad022..ddb7ff7 100644 --- a/openapi/s4_rsk.yaml +++ b/openapi/s4_rsk.yaml @@ -289,6 +289,8 @@ paths: created_at: '2026-10-01T00:00:00Z' updated_at: '2026-10-01T00:00:00Z' next_cursor: null + '401': + $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': @@ -317,6 +319,8 @@ paths: $ref: '#/components/schemas/RiskRule' '400': $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': @@ -351,6 +355,8 @@ paths: $ref: '#/components/schemas/RiskRule' '400': $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': @@ -378,6 +384,8 @@ paths: application/json: schema: $ref: '#/components/schemas/RuleRevisionPage' + '401': + $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': @@ -751,6 +759,12 @@ components: code: VALIDATION_ERROR detail: start must not be later than end. correlation_id: 7f3c1e52-5a0b-4a4f-9c1e-0d2b6a9f1c33 + Unauthorized: + description: The access token is missing, invalid or expired. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' Forbidden: description: The authenticated caller lacks the required role (`FORBIDDEN`). content: @@ -965,6 +979,7 @@ components: type: [string, 'null'] RiskRuleInput: type: object + additionalProperties: false description: For AMOUNT_LIMIT, parameters.max_amount is a positive integer amount in IRR (maximum 9223372036854775807). required: [name, type, parameters] properties: @@ -986,6 +1001,7 @@ components: format: date-time RiskRulePatch: type: object + additionalProperties: false description: For AMOUNT_LIMIT, parameters.max_amount is a positive integer amount in IRR (maximum 9223372036854775807). required: [expected_revision] properties: diff --git a/s4_rsk/common/openapi_contract.py b/s4_rsk/common/openapi_contract.py new file mode 100644 index 0000000..5286a92 --- /dev/null +++ b/s4_rsk/common/openapi_contract.py @@ -0,0 +1,124 @@ +"""Check real HTTP responses against an OpenAPI 3.1 contract file. + +The service is contract-first (ADR-002): ``openapi/s4_rsk.yaml`` is the agreement, +and the code must conform to it. ``assert_response_matches`` verifies that + +1. the status code is documented for the operation (exact code or ``4XX``/``5XX``), +2. the ``Content-Type`` is one the contract lists for that status, +3. the JSON body satisfies the documented schema, and +4. every response header the contract declares is present. + +It works with Django/DRF test responses and with ``httpx`` responses, so the same +helper validates our own API (provider tests) and a neighbour's API (consumer +contract tests). +""" + +from __future__ import annotations + +from functools import lru_cache +from pathlib import Path + +import yaml +from jsonschema import Draft202012Validator, FormatChecker + +REPO_ROOT = Path(__file__).resolve().parents[2] +PROVIDER_SPEC = REPO_ROOT / "openapi" / "s4_rsk.yaml" +NEIGHBOR_SPEC = REPO_ROOT / "openapi" / "neighbors" / "s2_ldg.yaml" + + +class ContractViolation(AssertionError): + """The observed response is not allowed by the contract.""" + + +@lru_cache(maxsize=None) +def load_spec(path: str | Path) -> dict: + return yaml.safe_load(Path(path).read_text(encoding="utf-8")) + + +def _resolve(spec: dict, node: dict) -> dict: + """Follow a local ``$ref`` such as ``#/components/responses/Forbidden``.""" + seen = 0 + while isinstance(node, dict) and "$ref" in node: + pointer = node["$ref"] + if not pointer.startswith("#/"): + raise ContractViolation(f"Only local $ref values are supported: {pointer}") + target = spec + for part in pointer[2:].split("/"): + target = target[part.replace("~1", "/").replace("~0", "~")] + node = target + seen += 1 + if seen > 20: + raise ContractViolation(f"$ref loop at {pointer}") + return node + + +def operation(spec: dict, path_template: str, method: str) -> dict: + try: + return spec["paths"][path_template][method.lower()] + except KeyError as exc: + raise ContractViolation(f"{method.upper()} {path_template} is not in the contract") from exc + + +def documented_statuses(spec: dict, path_template: str, method: str) -> list[str]: + return sorted(operation(spec, path_template, method)["responses"]) + + +def contract_example(spec: dict, path_template: str, method: str, status: str = "200") -> dict | list | None: + """Return the ``example`` the contract gives for a response (used to build stubs).""" + response = _resolve(spec, operation(spec, path_template, method)["responses"][status]) + media = next(iter(response.get("content", {}).values()), {}) + return media.get("example") + + +def _schema_validator(spec: dict, schema: dict) -> Draft202012Validator: + # The whole document is embedded so that "#/components/..." references resolve. + root = {"components": spec.get("components", {}), **schema} + return Draft202012Validator(root, format_checker=FormatChecker()) + + +def _header(response, name: str): + headers = getattr(response, "headers", None) + return headers.get(name) if headers is not None else None + + +def assert_response_matches(response, *, path_template: str, method: str, spec_path=PROVIDER_SPEC) -> None: + spec = load_spec(spec_path) + responses = operation(spec, path_template, method)["responses"] + status = str(response.status_code) + key = status if status in responses else f"{status[0]}XX" if f"{status[0]}XX" in responses else None + if key is None: + raise ContractViolation( + f"{method.upper()} {path_template} returned {status}, but the contract documents only {sorted(responses)}" + ) + declared = _resolve(spec, responses[key]) + + content = declared.get("content") or {} + if content: + content_type = (_header(response, "Content-Type") or "").split(";")[0].strip().lower() + media = content.get(content_type) + if media is None: + raise ContractViolation( + f"{method.upper()} {path_template} {status}: Content-Type {content_type!r} " + f"is not among {sorted(content)}" + ) + if "schema" in media: + errors = sorted( + _schema_validator(spec, media["schema"]).iter_errors(response.json()), + key=lambda error: tuple(str(part) for part in error.path), + ) + if errors: + lines = "; ".join(f"{'/'.join(map(str, e.path)) or ''}: {e.message}" for e in errors[:5]) + raise ContractViolation(f"{method.upper()} {path_template} {status} body violates the schema: {lines}") + + for header_name in declared.get("headers", {}): + if _header(response, header_name) is None: + raise ContractViolation(f"{method.upper()} {path_template} {status}: header {header_name} is missing") + + +def assert_payload_matches(schema_name: str, payload, *, spec_path=PROVIDER_SPEC) -> None: + """Check a request payload against ``components.schemas.``.""" + spec = load_spec(spec_path) + validator = _schema_validator(spec, {"$ref": f"#/components/schemas/{schema_name}"}) + errors = sorted(validator.iter_errors(payload), key=lambda error: list(error.path)) + if errors: + raise ContractViolation(f"Payload violates {schema_name}: {errors[0].message}") diff --git a/s4_rsk/common/test_health_contract.py b/s4_rsk/common/test_health_contract.py new file mode 100644 index 0000000..26c39fd --- /dev/null +++ b/s4_rsk/common/test_health_contract.py @@ -0,0 +1,33 @@ +"""Provider API tests for the probes against openapi/s4_rsk.yaml (no authentication needed).""" + +from unittest.mock import patch + +import pytest +from django.db import OperationalError +from rest_framework.test import APIClient + +from .openapi_contract import assert_response_matches + +pytestmark = pytest.mark.openapi + + +def test_health_matches_contract(): + response = APIClient().get("/health") + assert_response_matches(response, path_template="/health", method="get") + assert response.status_code == 200 + + +@pytest.mark.django_db +def test_ready_matches_contract_on_real_postgresql(): + response = APIClient().get("/ready") + assert_response_matches(response, path_template="/ready", method="get") + assert response.status_code == 200 + + +def test_ready_failure_is_documented_problem_details(): + with patch("common.views.connections") as connections: + connections.__getitem__.return_value.cursor.side_effect = OperationalError("down") + response = APIClient().get("/ready") + assert_response_matches(response, path_template="/ready", method="get") + assert response.status_code == 503 + assert response["Content-Type"] == "application/problem+json" diff --git a/s4_rsk/conftest.py b/s4_rsk/conftest.py new file mode 100644 index 0000000..3459e0f --- /dev/null +++ b/s4_rsk/conftest.py @@ -0,0 +1,17 @@ +import pytest + + +def pytest_addoption(parser): + parser.addoption( + "--run-neighbor-contract", action="store_true", default=False, + help="Run contract tests against the explicitly configured neighbour or stub.", + ) + + +def pytest_collection_modifyitems(config, items): + if config.getoption("--run-neighbor-contract"): + return + skip = pytest.mark.skip(reason="Pass --run-neighbor-contract to contact a running neighbour or stub") + for item in items: + if item.get_closest_marker("contract"): + item.add_marker(skip) diff --git a/s4_rsk/integrations/__init__.py b/s4_rsk/integrations/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/s4_rsk/integrations/ledger_client.py b/s4_rsk/integrations/ledger_client.py new file mode 100644 index 0000000..919e317 --- /dev/null +++ b/s4_rsk/integrations/ledger_client.py @@ -0,0 +1,168 @@ +"""Consumer client for the S2-LDG ledger service (our neighbour / provider). + +While assessing a transfer, S4-RSK reads the recent DEBIT entries of the source +account to spot unusual withdrawal patterns. Failures of the neighbour must never +break our own endpoint: they are translated into a safe REVIEW signal. + +The neighbour's address is read from ``NEIGHBOR_BASE_URL`` (see ``resolve_base_url``); +``S2_LDG_BASE_URL`` from .env is the fallback. + +Status of the integration: this module is the tested client. It is not yet called by +``assessments.services`` (that wiring belongs to US-01B). +""" + +from __future__ import annotations + +import os +from dataclasses import dataclass +from datetime import datetime +from urllib.parse import quote +from uuid import UUID + +import httpx + +DEFAULT_TIMEOUT_SECONDS = 2.0 +MAX_PAGES = 10 +ENTRIES_PATH = "/api/v1/accounts/{account_id}/entries" + +STATUS_OK = "OK" +STATUS_ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND" +STATUS_LEDGER_UNAVAILABLE = "LEDGER_UNAVAILABLE" + + +class LedgerError(Exception): + """The ledger answer cannot be used.""" + + +class LedgerAccountNotFound(LedgerError): + """S2-LDG answered 404 for the account.""" + + +class LedgerUnavailable(LedgerError): + """Timeout, connection failure or 5xx from S2-LDG.""" + + +@dataclass(frozen=True) +class LedgerEntry: + id: str + account_id: str + direction: str + amount: int + occurred_at: datetime + + +@dataclass(frozen=True) +class LedgerHistory: + """What the rule engine receives; ``forced_decision`` is set when history is unusable.""" + + status: str + entries: tuple[LedgerEntry, ...] = () + forced_decision: str | None = None + + @property + def reason_code(self) -> str | None: + return None if self.status == STATUS_OK else self.status + + +def resolve_base_url(explicit: str | None = None) -> str: + """NEIGHBOR_BASE_URL is the single place where the neighbour address is read.""" + url = explicit or os.environ.get("NEIGHBOR_BASE_URL") or os.environ.get("S2_LDG_BASE_URL") + if not url: + raise LedgerError("NEIGHBOR_BASE_URL is not configured.") + return url.rstrip("/") + + +def _parse_entry(raw: dict) -> LedgerEntry: + try: + if not isinstance(raw, dict): + raise ValueError("entry must be an object") + amount = raw["amount"] + if isinstance(amount, bool) or not isinstance(amount, int) or amount < 1: + raise ValueError("amount must be a positive integer") + if raw["direction"] != "DEBIT": + raise ValueError("entry must be a debit") + UUID(str(raw["id"])) + UUID(str(raw["account_id"])) + occurred_at = datetime.fromisoformat(raw["occurred_at"]) + if occurred_at.utcoffset() is None: + raise ValueError("occurred_at must include a timezone") + return LedgerEntry( + id=str(raw["id"]), + account_id=str(raw["account_id"]), + direction=str(raw["direction"]), + amount=amount, + occurred_at=occurred_at, + ) + except (KeyError, TypeError, ValueError) as exc: + raise LedgerError(f"Malformed ledger entry: {exc}") from exc + + +class LedgerClient: + def __init__( + self, + base_url: str | None = None, + *, + timeout: float = DEFAULT_TIMEOUT_SECONDS, + transport: httpx.BaseTransport | None = None, + token: str | None = None, + ): + self._base_url = resolve_base_url(base_url) + self._timeout = timeout + self._transport = transport + self._token = token + + def recent_debits(self, account_id, since: datetime, *, correlation_id: str | None = None) -> list[LedgerEntry]: + headers = {"Accept": "application/json"} + if correlation_id: + headers["X-Correlation-ID"] = correlation_id + if self._token: + headers["Authorization"] = f"Bearer {self._token}" + url = ENTRIES_PATH.format(account_id=quote(str(account_id), safe="")) + entries: list[LedgerEntry] = [] + cursor: str | None = None + + with httpx.Client(base_url=self._base_url, timeout=self._timeout, transport=self._transport) as http: + for _ in range(MAX_PAGES): + params = {"direction": "DEBIT", "from": since.isoformat(), "limit": 200} + if cursor: + params["cursor"] = cursor + try: + response = http.get(url, params=params, headers=headers) + except httpx.HTTPError as exc: # timeout, connection refused, protocol error + raise LedgerUnavailable(f"Ledger request failed: {type(exc).__name__}") from exc + + if response.status_code == 404: + raise LedgerAccountNotFound(str(account_id)) + if response.status_code >= 500: + raise LedgerUnavailable(f"Ledger answered {response.status_code}") + if response.status_code != 200: + raise LedgerError(f"Unexpected ledger status {response.status_code}") + try: + body = response.json() + items = body["items"] + cursor = body.get("next_cursor") + if not isinstance(items, list) or (cursor is not None and not isinstance(cursor, str)): + raise ValueError("invalid page") + except (ValueError, KeyError, TypeError) as exc: + raise LedgerError("Ledger answered 200 with an unreadable body") from exc + for item in items: + entry = _parse_entry(item) + if entry.account_id != str(account_id): + raise LedgerError("Ledger returned an entry for a different account") + entries.append(entry) + if not cursor: + return entries + raise LedgerError("Ledger returned too many pages") + + +def assess_ledger_history( + client: LedgerClient, account_id, since: datetime, *, correlation_id: str | None = None +) -> LedgerHistory: + """Never raises: turns every neighbour failure into an explicit REVIEW signal.""" + try: + entries = client.recent_debits(account_id, since, correlation_id=correlation_id) + except LedgerAccountNotFound: + return LedgerHistory(STATUS_ACCOUNT_NOT_FOUND, forced_decision="REVIEW") + except LedgerError: + return LedgerHistory(STATUS_LEDGER_UNAVAILABLE, forced_decision="REVIEW") + return LedgerHistory(STATUS_OK, tuple(entries)) diff --git a/s4_rsk/integrations/test_ledger_client_stub.py b/s4_rsk/integrations/test_ledger_client_stub.py new file mode 100644 index 0000000..19a4cf0 --- /dev/null +++ b/s4_rsk/integrations/test_ledger_client_stub.py @@ -0,0 +1,184 @@ +"""Consumer tests: S4-RSK's ledger client against a Stub of S2-LDG (no neighbour needed). + +The stub answers are taken from the examples of the neighbour's OpenAPI file +(openapi/neighbors/s2_ldg.yaml), so the tests stay tied to the draft contract. +The asserts check the behaviour of OUR code (decision signal), not only that the stub was called. +""" + +import uuid +from datetime import UTC, datetime + +import httpx +import pytest + +from common.openapi_contract import NEIGHBOR_SPEC, contract_example, load_spec + +from .ledger_client import ( + STATUS_ACCOUNT_NOT_FOUND, + STATUS_LEDGER_UNAVAILABLE, + STATUS_OK, + LedgerClient, + LedgerError, + assess_ledger_history, + resolve_base_url, +) + +PATH = "/api/v1/accounts/{account_id}/entries" +SPEC = load_spec(NEIGHBOR_SPEC) +OK_BODY = contract_example(SPEC, PATH, "get", "200") +NOT_FOUND_BODY = contract_example(SPEC, PATH, "get", "404") +UNAVAILABLE_BODY = contract_example(SPEC, PATH, "get", "503") + +ACCOUNT_ID = uuid.UUID("0192f5a0-5555-7aaa-8bbb-0123456789ab") +SINCE = datetime(2026, 10, 24, 0, 0, tzinfo=UTC) + + +def _client(handler, base_url="http://s2-ldg.test"): + return LedgerClient(base_url, transport=httpx.MockTransport(handler)) + + +def test_success_returns_parsed_debits_and_sends_the_draft_request(): + seen = {} + + def handler(request: httpx.Request) -> httpx.Response: + seen["path"] = request.url.path + seen["params"] = dict(request.url.params) + seen["correlation"] = request.headers.get("X-Correlation-ID") + return httpx.Response(200, json=OK_BODY) + + history = assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE, correlation_id="stub-cid-1") + + assert seen["path"] == f"/api/v1/accounts/{ACCOUNT_ID}/entries" + assert seen["params"]["direction"] == "DEBIT" + assert seen["params"]["from"] == "2026-10-24T00:00:00+00:00" + assert seen["correlation"] == "stub-cid-1" + assert history.status == STATUS_OK + assert history.forced_decision is None + assert [entry.amount for entry in history.entries] == [1_500_000, 700_000] + assert all(entry.occurred_at.tzinfo is not None for entry in history.entries) + + +def test_pagination_follows_next_cursor_until_exhausted(): + calls = [] + + def handler(request: httpx.Request) -> httpx.Response: + calls.append(request.url.params.get("cursor")) + if request.url.params.get("cursor") is None: + return httpx.Response(200, json={"items": OK_BODY["items"][:1], "next_cursor": "page-2"}) + return httpx.Response(200, json={"items": OK_BODY["items"][1:], "next_cursor": None}) + + entries = _client(handler).recent_debits(ACCOUNT_ID, SINCE) + + assert calls == [None, "page-2"] + assert len(entries) == 2 + + +def test_unknown_account_forces_review_with_explicit_reason(): + def handler(request): + return httpx.Response(404, json=NOT_FOUND_BODY, headers={"Content-Type": "application/problem+json"}) + + history = assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE) + + assert history.reason_code == STATUS_ACCOUNT_NOT_FOUND + assert history.forced_decision == "REVIEW" + assert history.entries == () + + +def test_timeout_forces_review_instead_of_raising(): + def handler(request): + raise httpx.ConnectTimeout("simulated timeout", request=request) + + history = assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE) + + assert history.reason_code == STATUS_LEDGER_UNAVAILABLE + assert history.forced_decision == "REVIEW" + + +def test_server_error_forces_review(): + def handler(request): + return httpx.Response(503, json=UNAVAILABLE_BODY, headers={"Content-Type": "application/problem+json"}) + + history = assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE) + + assert history.reason_code == STATUS_LEDGER_UNAVAILABLE + assert history.forced_decision == "REVIEW" + + +def test_malformed_success_body_is_not_trusted(): + bad_entry = {"id": "x", "account_id": "y", "direction": "DEBIT", "occurred_at": "2026-10-24T08:00:00Z"} + + def handler(request): + return httpx.Response(200, json={"items": [bad_entry], "next_cursor": None}) + + with pytest.raises(LedgerError): + _client(handler).recent_debits(ACCOUNT_ID, SINCE) + assert assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE).forced_decision == "REVIEW" + + +@pytest.mark.parametrize("body", [{"items": None}, {"items": [] , "next_cursor": 1}, {"items": [None]}]) +def test_malformed_page_is_reported_as_unavailable(body): + def handler(request): + return httpx.Response(200, json=body) + + history = assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE) + assert history.reason_code == STATUS_LEDGER_UNAVAILABLE + assert history.forced_decision == "REVIEW" + + +def test_entry_for_another_account_is_rejected(): + entry = {**OK_BODY["items"][0], "account_id": "0192f5a0-9999-7aaa-8bbb-000000000000"} + + def handler(request): + return httpx.Response(200, json={"items": [entry], "next_cursor": None}) + + assert assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE).reason_code == STATUS_LEDGER_UNAVAILABLE + + +def test_neighbor_base_url_environment_variable_selects_the_host(monkeypatch): + monkeypatch.setenv("NEIGHBOR_BASE_URL", "http://neighbour.invalid:9999/") + hosts = [] + + def handler(request): + hosts.append((request.url.host, request.url.port)) + return httpx.Response(200, json=OK_BODY) + + LedgerClient(transport=httpx.MockTransport(handler)).recent_debits(ACCOUNT_ID, SINCE) + + assert hosts == [("neighbour.invalid", 9999)] + + +def test_missing_neighbor_base_url_is_a_clear_error(monkeypatch): + monkeypatch.delenv("NEIGHBOR_BASE_URL", raising=False) + monkeypatch.delenv("S2_LDG_BASE_URL", raising=False) + with pytest.raises(LedgerError, match="NEIGHBOR_BASE_URL"): + resolve_base_url() + + +def test_unexpected_client_error_is_not_treated_as_empty_history(): + def handler(request): + return httpx.Response(403, json={"code": "FORBIDDEN"}) + + with pytest.raises(LedgerError, match="403"): + _client(handler).recent_debits(ACCOUNT_ID, SINCE) + assert assess_ledger_history(_client(handler), ACCOUNT_ID, SINCE).forced_decision == "REVIEW" + + +def test_endless_cursor_chain_is_cut_off(): + def handler(request): + return httpx.Response(200, json={"items": [], "next_cursor": "again"}) + + with pytest.raises(LedgerError, match="too many pages"): + _client(handler).recent_debits(ACCOUNT_ID, SINCE) + + +def test_bearer_token_is_sent_when_configured(): + seen = {} + + def handler(request): + seen["authorization"] = request.headers.get("Authorization") + return httpx.Response(200, json=OK_BODY) + + client = LedgerClient("http://s2-ldg.test", transport=httpx.MockTransport(handler), token="stub-token") + client.recent_debits(ACCOUNT_ID, SINCE) + + assert seen["authorization"] == "Bearer stub-token" diff --git a/s4_rsk/integrations/test_ledger_contract.py b/s4_rsk/integrations/test_ledger_contract.py new file mode 100644 index 0000000..4ce14a1 --- /dev/null +++ b/s4_rsk/integrations/test_ledger_contract.py @@ -0,0 +1,66 @@ +"""Consumer contract tests: our expectations against a RUNNING provider. + +Target: NEIGHBOR_BASE_URL - either a Prism mock built from the neighbour's contract +(http://127.0.0.1:4010) or the neighbour's real service (bonus, section 12). + + prism mock openapi/neighbors/s2_ldg.yaml -p 4010 + $env:NEIGHBOR_BASE_URL="http://127.0.0.1:4010" + pytest -m contract --run-neighbor-contract -v -s + +Optional: NEIGHBOR_ACCOUNT_ID_OK / NEIGHBOR_ACCOUNT_ID_MISSING select the seeded account ids. +""" + +import os +from datetime import UTC, datetime + +import httpx +import pytest + +from common.openapi_contract import NEIGHBOR_SPEC, assert_response_matches + +from .ledger_client import STATUS_ACCOUNT_NOT_FOUND, STATUS_OK, LedgerClient, assess_ledger_history + +BASE_URL = os.environ.get("NEIGHBOR_BASE_URL", "").rstrip("/") +ACCOUNT_OK = os.environ.get("NEIGHBOR_ACCOUNT_ID_OK", "0192f5a0-5555-7aaa-8bbb-0123456789ab") +ACCOUNT_MISSING = os.environ.get("NEIGHBOR_ACCOUNT_ID_MISSING", "0192f5a0-9999-7aaa-8bbb-000000000000") +SINCE = datetime(2026, 10, 24, tzinfo=UTC) +PATH = "/api/v1/accounts/{account_id}/entries" + +pytestmark = [ + pytest.mark.contract, + pytest.mark.skipif(not BASE_URL, reason="NEIGHBOR_BASE_URL is not set"), +] + + +def stamp(message: str) -> None: + print(f"[{datetime.now(UTC).isoformat(timespec='milliseconds')}] {message}") + + +def _get(account_id: str, **extra_headers) -> httpx.Response: + url = f"{BASE_URL}/api/v1/accounts/{account_id}/entries" + stamp(f"GET {url}") + response = httpx.get(url, params={"direction": "DEBIT"}, headers=extra_headers, timeout=5.0) + stamp(f"-> {response.status_code} {response.headers.get('content-type')}") + return response + + +def test_success_response_matches_neighbor_contract(): + response = _get(ACCOUNT_OK) + assert response.status_code == 200 + assert_response_matches(response, path_template=PATH, method="get", spec_path=NEIGHBOR_SPEC) + + +def test_unknown_account_response_matches_neighbor_contract(): + # "Prefer: code=404" makes a Prism mock return its 404 example; a real provider ignores it. + response = _get(ACCOUNT_MISSING, Prefer="code=404") + assert response.status_code == 404 + assert response.headers["content-type"].startswith("application/problem+json") + assert_response_matches(response, path_template=PATH, method="get", spec_path=NEIGHBOR_SPEC) + + +def test_our_client_understands_the_real_success_response(): + stamp("LedgerClient.recent_debits against the running neighbour") + history = assess_ledger_history(LedgerClient(BASE_URL), ACCOUNT_OK, SINCE) + stamp(f"-> status={history.status} entries={len(history.entries)}") + assert history.status == STATUS_OK + assert history.status != STATUS_ACCOUNT_NOT_FOUND diff --git a/s4_rsk/pytest.ini b/s4_rsk/pytest.ini index 4167098..8e4a310 100644 --- a/s4_rsk/pytest.ini +++ b/s4_rsk/pytest.ini @@ -3,3 +3,6 @@ DJANGO_SETTINGS_MODULE = config.settings pythonpath = . python_files = tests.py test_*.py *_tests.py addopts = --reuse-db -v +markers = + openapi: provider response conforms to its OpenAPI contract + contract: optional tests against a running neighbour or Prism stub diff --git a/s4_rsk/rules/test_rule_contract.py b/s4_rsk/rules/test_rule_contract.py new file mode 100644 index 0000000..b150ad2 --- /dev/null +++ b/s4_rsk/rules/test_rule_contract.py @@ -0,0 +1,132 @@ +"""Provider API tests: every response of the rule endpoints must match openapi/s4_rsk.yaml. + +Run only these tests with: pytest -m openapi -v +""" + +import pytest +from django.contrib.auth.models import Group +from rest_framework.test import APIClient +from rest_framework_simplejwt.tokens import AccessToken + +from common.openapi_contract import assert_payload_matches, assert_response_matches + +from .models import RiskRule + +URL = "/api/v1/risk-rules" +pytestmark = [pytest.mark.django_db, pytest.mark.openapi] + + +def _client_for(user): + client = APIClient() + client.credentials(HTTP_AUTHORIZATION=f"Bearer {AccessToken.for_user(user)}") + return client + + +@pytest.fixture +def manager(django_user_model): + user = django_user_model.objects.create_user("contract-manager") + user.groups.add(Group.objects.get_or_create(name="manager")[0]) + return user + + +@pytest.fixture +def client(manager): + return _client_for(manager) + + +@pytest.fixture +def payload(): + return {"name": "contract limit", "type": "AMOUNT_LIMIT", "parameters": {"max_amount": 5_000_000}} + + +def _create(client, payload): + response = client.post(URL, payload, format="json") + assert response.status_code == 201 + return response.json() + + +def test_list_matches_contract(client, payload): + _create(client, payload) + response = client.get(URL) + assert_response_matches(response, path_template="/risk-rules", method="get") + assert response.status_code == 200 + + +def test_create_matches_contract(client, payload): + assert_payload_matches("RiskRuleInput", payload) + response = client.post(URL, payload, format="json") + assert_response_matches(response, path_template="/risk-rules", method="post") + assert response.status_code == 201 + assert response.json()["revision"] == 1 + + +def test_invalid_amount_is_documented_problem_details(client, payload): + payload["parameters"] = {"max_amount": 0} + response = client.post(URL, payload, format="json") + assert_response_matches(response, path_template="/risk-rules", method="post") + assert response.status_code == 400 + assert response["Content-Type"] == "application/problem+json" + assert response.json()["code"] == "VALIDATION_ERROR" + + +def test_stale_revision_is_documented_conflict(client, payload): + rule = _create(client, payload) + response = client.patch(f"{URL}/{rule['id']}", {"expected_revision": 99, "name": "x"}, format="json") + assert_response_matches(response, path_template="/risk-rules/{rule_id}", method="patch") + assert response.status_code == 409 + assert response.json()["code"] == "CONFLICT" + + +def test_patch_success_matches_contract(client, payload): + rule = _create(client, payload) + body = {"expected_revision": 1, "parameters": {"max_amount": 9_000_000}} + assert_payload_matches("RiskRulePatch", body) + response = client.patch(f"{URL}/{rule['id']}", body, format="json") + assert_response_matches(response, path_template="/risk-rules/{rule_id}", method="patch") + assert response.json()["revision"] == 2 + + +def test_audit_matches_contract(client, payload): + rule = _create(client, payload) + response = client.get(f"{URL}/{rule['id']}/audit") + assert_response_matches(response, path_template="/risk-rules/{rule_id}/audit", method="get") + assert response.status_code == 200 + + +def test_unknown_rule_is_documented_not_found(client): + response = client.patch( + f"{URL}/019a0100-0000-7000-8000-00000000ffff", {"expected_revision": 1, "name": "x"}, format="json" + ) + assert_response_matches(response, path_template="/risk-rules/{rule_id}", method="patch") + assert response.status_code == 404 + + +def test_missing_token_is_a_documented_401(): + response = APIClient().get(URL) + assert response.status_code == 401 + assert_response_matches(response, path_template="/risk-rules", method="get") + + +def test_non_manager_is_a_documented_403(django_user_model): + user = django_user_model.objects.create_user("contract-no-role") + response = _client_for(user).get(URL) + assert response.status_code == 403 + assert_response_matches(response, path_template="/risk-rules", method="get") + + +def test_idempotency_key_reuse_uses_the_code_named_in_the_contract(client, payload): + key = "019a0100-0000-7000-8000-0000000000aa" + assert client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY=key).status_code == 201 + response = client.post(URL, {**payload, "name": "other"}, format="json", HTTP_IDEMPOTENCY_KEY=key) + assert_response_matches(response, path_template="/risk-rules", method="post") + assert response.status_code == 409 + assert response.json()["code"] == "IDEMPOTENCY_KEY_REUSED" + assert RiskRule.objects.count() == 1 + + +def test_invalid_idempotency_key_is_a_validation_problem(client, payload): + response = client.post(URL, payload, format="json", HTTP_IDEMPOTENCY_KEY="not-a-uuid") + assert_response_matches(response, path_template="/risk-rules", method="post") + assert response.status_code == 400 + assert response.json()["code"] == "VALIDATION_ERROR" + assert RiskRule.objects.count() == 0