From e03248b1c868a38b6e6e3f156a13523a326fddd2 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Sat, 5 Sep 2026 13:27:32 +0400 Subject: [PATCH 1/2] docs: add Insomnia auth MFA transfer workflows --- README.md | 4 + docs/insomnia-auth-session-workflow.md | 122 ++++++++++++ docs/insomnia-mfa-workflow.md | 135 ++++++++++++++ docs/insomnia-step-up-transfer-workflow.md | 204 +++++++++++++++++++++ docs/insomnia-transfer-workflow.md | 179 ++++++++++++++++++ 5 files changed, 644 insertions(+) create mode 100644 docs/insomnia-auth-session-workflow.md create mode 100644 docs/insomnia-mfa-workflow.md create mode 100644 docs/insomnia-step-up-transfer-workflow.md create mode 100644 docs/insomnia-transfer-workflow.md diff --git a/README.md b/README.md index ec9006e..694dbb6 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ This repository is not a deployable application. It provides shared contributor - [Reproducible local Kubernetes SIT setup and verification](docs/local-sit.md) - [Platform naming, ports, configuration, API, and infrastructure conventions](docs/platform-conventions.md) - [Workstation debugging against SIT](docs/workstation-debugging-against-sit.md) +- [Insomnia auth and session workflow](docs/insomnia-auth-session-workflow.md) +- [Insomnia MFA workflow](docs/insomnia-mfa-workflow.md) +- [Insomnia internal transfer workflow](docs/insomnia-transfer-workflow.md) +- [Insomnia step-up transfer workflow](docs/insomnia-step-up-transfer-workflow.md) - [README documentation baseline](docs/readme-standard.md) ## Contribution Workflow diff --git a/docs/insomnia-auth-session-workflow.md b/docs/insomnia-auth-session-workflow.md new file mode 100644 index 0000000..c233a51 --- /dev/null +++ b/docs/insomnia-auth-session-workflow.md @@ -0,0 +1,122 @@ +# Insomnia Auth And Session Workflow + +This guide is a repeatable manual check of authentication and server-side +session behavior through the API Gateway in local Kubernetes SIT. It does not +replace Auth Service tests, gateway tests, or deployment checks. + +## Preconditions + +Confirm the local SIT cluster, Auth Service, and API Gateway are healthy: + +```bash +kubectl config use-context docker-desktop +kubectl get deployments,pods,services --namespace digital-bank-sit +kubectl port-forward --namespace digital-bank-sit service/api-gateway 8080:8080 +``` + +Use `http://localhost:8080` as the workstation gateway URL, or the selected +forwarded port if `8080` is occupied. Use the gateway for every request in +this guide; do not add a direct Auth Service URL to the shared environment. + +## Environment + +Use one Insomnia workspace with a Base Environment and named `SIT`, `UAT`, +and `PROD` child environments. The Base Environment contains names and empty +placeholders only: + +```json +{ + "apiGatewayUrl": "", + "authUsername": "", + "authPassword": "", + "authAccessToken": "", + "authSessionId": "" +} +``` + +Keep usernames, passwords, bearer tokens, and session IDs in private/local +values. Do not export or sync those values. `SIT` is the active local +environment; `UAT` and `PROD` require approved gateway URLs and test +identities. `local` and `LOCAL-DEV` are not supported environments. + +## Login + +Select `SIT` and send: + +```http +POST {{ apiGatewayUrl }}/api/v1/auth/login +Content-Type: application/json + +{ + "username": "{{ authUsername }}", + "password": "{{ authPassword }}" +} +``` + +Expect `200 OK` with `accessToken`, `tokenType: "Bearer"`, `sessionId`, and +`expiresAt`. The signed JWT contains `sub`, `sid`, `active`, `iss`, `iat`, and +`exp`, plus the configured space-delimited `scope` claim. The JWT `sid` must +match the response `sessionId`. Store only the token and session ID in private +local values. + +With the default `REVOKE_PREVIOUS` session policy, a second successful login +for the same username revokes the earlier active session. The newest token +remains usable and the earlier token must fail once server-side session +validation is enforced. + +## Protected Session Check + +Use an already-defined protected request from the service workflow under test, +for example the transfer read request in +[the internal transfer guide](insomnia-transfer-workflow.md): + +```http +GET {{ apiGatewayUrl }}/internal/v1/transfer-workflows/{{ transferId }} +Authorization: Bearer {{ authAccessToken }} +``` + +Do not invent a placeholder endpoint merely to test authentication. A +successful protected response confirms the gateway accepted the bearer token +and the server-side session is active for that route. Then repeat the same +request with these controlled variations: + +1. Remove the `Authorization` header. Expect `401 Unauthorized`. +2. Change one character in the token. Expect `401 Unauthorized`. +3. Log out, then repeat the request with the same token. Expect `401 + Unauthorized` after revocation enforcement is deployed. + +## Logout And Revocation + +Send: + +```http +POST {{ apiGatewayUrl }}/api/v1/auth/logout +Authorization: Bearer {{ authAccessToken }} +``` + +Expect `204 No Content`. Repeat the request with the same valid token shape; +logout is idempotent and should return `204` again. Repeat the protected +request and confirm that the revoked session is rejected. Clear the private +token and session values after the check. + +## Failure Checks + +| Check | Expected result | +| --- | --- | +| Blank or malformed login payload | `400` `application/problem+json` with validation errors | +| Unknown username or wrong password | `401` authentication-failed Problem Details | +| Missing, malformed, invalid, expired, or revoked bearer | `401` invalid-token Problem Details | +| Repeated logout with a valid token | `204 No Content` | +| Gateway route unavailable or returns `404` | Check gateway/configuration rollout; do not bypass the gateway | + +Never record passwords, raw JWTs, Authorization headers, customer data, or +private environment values in issues, PRs, screenshots, or logs. Share only +redacted status codes, problem types, and opaque identifiers. + +## Dependencies And Boundaries + +The auth/session implementation is in [Auth Service PR #7](https://github.com/digital-bank-java/auth-service/pull/7), with the JWT/session foundation in [PRs #2-#6](https://github.com/digital-bank-java/auth-service/pulls?q=is%3Apr+is%3Amerged). Gateway route and scope enforcement are in [API Gateway PR #23](https://github.com/digital-bank-java/api-gateway/pull/23) and [Config Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39). Use the workflow only after the relevant service, configuration, and gateway revisions are deployed in SIT. + +The current Auth Service API intentionally provides login and logout only. It +does not expose a public session-introspection or refresh endpoint, so no such +request is included here. diff --git a/docs/insomnia-mfa-workflow.md b/docs/insomnia-mfa-workflow.md new file mode 100644 index 0000000..acd784e --- /dev/null +++ b/docs/insomnia-mfa-workflow.md @@ -0,0 +1,135 @@ +# Insomnia MFA Workflow + +This guide verifies the generic MFA enrollment and challenge lifecycle through +the API Gateway. Use synthetic SIT identities only. The transfer-bound +step-up flow is documented separately in +[the step-up transfer guide](insomnia-step-up-transfer-workflow.md). + +## Preconditions And Environment + +The API Gateway port-forward, MFA Service, Auth Service, and the gateway MFA +route must be healthy. The route/configuration dependency is [Config Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39). + +Use the shared Insomnia Base Environment and select `SIT`: + +| Variable | Purpose | +| --- | --- | +| `apiGatewayUrl` | API Gateway port-forward, normally `http://localhost:8080` | +| `authAccessToken` | Private internal JWT with the configured MFA scope | +| `mfaEnrollmentId` | Opaque enrollment ID captured from creation | +| `mfaChallengeId` | Opaque challenge ID captured from creation | +| `mfaCode` | Private six-digit code from the approved authenticator | + +Keep all credentials, tokens, codes, and identifiers in private/local values. +Do not add a direct MFA Service URL to a shared environment. + +Every authenticated request uses: + +```http +Authorization: Bearer {{ authAccessToken }} +``` + +## 1. Create Enrollment + +Enrollment ownership is derived from the authenticated JWT `sub` claim. The +legacy `subjectId` field is accepted for compatibility but ignored, so do not +add it to a new request: + +```http +POST {{ apiGatewayUrl }}/api/v1/mfa/enrollments +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{} +``` + +Expect `201 Created` with an opaque `enrollmentId`, `status: "ENROLLED"`, and +`enrollmentStatus: "PENDING"`. Capture the ID as `mfaEnrollmentId`. The +response must not contain a TOTP secret or provisioning URI. + +The current service contract does not expose a secret/provisioning response. +An approved platform authenticator path must provision the enrollment before +the next request can succeed. Do not guess a code or add a secret field. + +## 2. Verify Enrollment + +After the approved authenticator path supplies a valid code, send: + +```http +POST {{ apiGatewayUrl }}/api/v1/mfa/enrollments/{{ mfaEnrollmentId }}/verifications +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "code": "{{ mfaCode }}" +} +``` + +Expect `200 OK` with `status: "ACTIVATED"` and +`enrollmentStatus: "ACTIVE"`. A wrong six-digit code returns `401` Problem +Details; an unknown or foreign enrollment returns `404`; an already active +enrollment returns `409`. + +## 3. Create Challenge + +Once the enrollment is active, send: + +```http +POST {{ apiGatewayUrl }}/api/v1/mfa/challenges +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "enrollmentId": "{{ mfaEnrollmentId }}" +} +``` + +Expect `201 Created` with an opaque `challengeId`, +`challengeStatus: "OPEN"`, `expiresAt`, and `remainingAttempts`. Capture the +ID as `mfaChallengeId`. + +## 4. Verify Challenge + +Submit the current code: + +```http +POST {{ apiGatewayUrl }}/api/v1/mfa/challenges/{{ mfaChallengeId }}/verifications +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "code": "{{ mfaCode }}" +} +``` + +Expect `200 OK` with `status: "VERIFIED"` and +`challengeStatus: "CONSUMED"`. The challenge is single-use. + +## Negative Checks + +| Check | Expected result | +| --- | --- | +| Missing, malformed, expired, or revoked bearer | `401` `application/problem+json` | +| Authenticated principal without the MFA scope | `403` `application/problem+json` | +| Non-six-digit verification code | `400` validation Problem Details | +| Unknown or foreign enrollment/challenge | `404` resource-not-found Problem Details | +| Wrong six-digit code | `401` invalid-code Problem Details; attempts decrease | +| Expired challenge | `401` challenge-expired Problem Details | +| Exhausted challenge | `401` challenge-exhausted Problem Details | +| Replayed consumed challenge | `401` challenge-replayed Problem Details | +| Challenge created before enrollment is active | `409` enrollment-not-active Problem Details | + +The MFA Service also enforces authenticated-principal ownership. Do not use a +different JWT subject to access an existing enrollment or challenge. + +## Evidence And Boundaries + +Record only the environment, date, request names, status codes, redacted +problem types, and opaque IDs where policy permits. Never record bearer +tokens, submitted codes, TOTP secrets, provisioning material, or raw response +dumps. + +This generic workflow does not authorize a transfer, mutate account balances, +or publish transfer assurance. Successful transfer-bound verification and its +event handoff are covered by the separate step-up guide. The MFA Service has +no customer login, session management, recovery-code, or direct account API. diff --git a/docs/insomnia-step-up-transfer-workflow.md b/docs/insomnia-step-up-transfer-workflow.md new file mode 100644 index 0000000..e3aaa54 --- /dev/null +++ b/docs/insomnia-step-up-transfer-workflow.md @@ -0,0 +1,204 @@ +# Insomnia Step-Up Transfer Workflow + +This guide exercises the existing risk-gated internal transfer and +transfer-bound MFA workflow through the API Gateway. It covers the +`REQUIRE_STEP_UP` decision, challenge binding, one-time verification, and +event-driven continuation. It does not add a transfer approval endpoint, +change risk thresholds, or call a downstream service directly. + +## Implemented Boundary + +The workflow is owned by existing service contracts: + +1. Transaction Service evaluates the transfer intent and persists a risk + decision. +2. `REQUIRE_STEP_UP` leaves the transfer non-postable with no reservation + action and exposes the risk decision identifiers. +3. MFA Service creates and verifies a challenge bound to that exact transfer + and decision. +4. Successful verification publishes `MfaAssuranceGranted.v1` through the + MFA outbox. +5. Transaction Service consumes the assurance, revalidates the binding and + expiry, and resumes its reservation action. + +The synchronous HTTP calls stop after MFA verification. Assurance publication +and transfer continuation are verified through the event and transfer read +contracts, not by inventing a `POST /approve` or `POST /resume` route. + +## Preconditions And Variables + +Use the local Kubernetes SIT gateway port-forward from the +[local SIT guide](local-sit.md). The Auth, MFA, Transaction, and gateway +rollouts must be healthy. Gateway routing/security and SIT configuration are +provided by [Config Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39), [API Gateway PR #23](https://github.com/digital-bank-java/api-gateway/pull/23), and the related service releases. + +Use private/local values for: + +| Variable | Purpose | +| --- | --- | +| `apiGatewayUrl` | Gateway port-forward, normally `http://localhost:8080` | +| `authAccessToken` | Authenticated JWT with `transfer.internal` and MFA access | +| `transferId` | Fresh transfer UUID | +| `sourceAccountId` | Synthetic source account UUID | +| `destinationAccountId` | Synthetic destination account UUID | +| `amount` | Synthetic risk-test amount, normally `12500.0000` AED | +| `currency` | `AED` or another configured risk currency | +| `correlationId` | Stable transfer correlation identifier | +| `transferRequestId` | Stable transfer request identifier | +| `reservationRequestId` | Stable reservation identifier | +| `postingRequestId` | Stable posting identifier | +| `decisionRequestId` | Stable risk decision request identifier | +| `mfaEnrollmentId` | Active enrollment ID for the authenticated subject | +| `riskDecisionId` | Returned `riskDecisionId` from the transfer response | +| `riskDecisionRequestId` | Returned decision request ID | +| `riskPolicyVersion` | Returned risk policy version | +| `mfaChallengeId` | Returned transfer-bound challenge ID | +| `mfaCode` | Private current TOTP code | + +The default SIT risk policy requires step-up for `INTERNATIONAL` destination +class or an AED/USD amount at or above `10000`. Confirm the deployed policy +before running the test; configuration is authoritative. + +## 1. Create A Step-Up Transfer + +Authenticate using the auth/session workflow, then send a fresh transfer with +a configured step-up condition. The example uses the default high-value +condition: + +```http +POST {{ apiGatewayUrl }}/internal/v1/transfer-workflows +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "transferId": "{{ transferId }}", + "sourceAccountId": "{{ sourceAccountId }}", + "destinationAccountId": "{{ destinationAccountId }}", + "amount": 12500.0000, + "currency": "AED", + "correlationId": "{{ correlationId }}", + "transferRequestId": "{{ transferRequestId }}", + "reservationRequestId": "{{ reservationRequestId }}", + "postingRequestId": "{{ postingRequestId }}", + "decisionRequestId": "{{ decisionRequestId }}", + "channel": "INTERNAL", + "destinationClass": "INTERNAL" +} +``` + +Expect `201 Created`, `riskOutcome: "REQUIRE_STEP_UP"`, +`riskRequiredAssurance: "MFA"`, `riskChallengeType: "TOTP"`, a non-expired +`riskDecisionId`, and no reservation action. The risk-gated workflow should +remain in `AWAITING_STEP_UP` on the current Transaction Service release. Keep +the following response values unchanged: transfer ID, reservation request ID, +decision ID, decision request ID, account IDs, amount, currency, policy +version, and correlation ID. + +If the response is `ALLOW`, the deployed risk configuration did not classify +the request as step-up. Stop and use the configured test condition; do not +pretend that an ALLOW response is a step-up result. + +## 2. Create The Transfer-Bound MFA Challenge + +The authenticated subject must have an active enrollment. The request binds +the challenge to the exact transfer and risk decision: + +```http +POST {{ apiGatewayUrl }}/api/v1/mfa/transfer-challenges +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "enrollmentId": "{{ mfaEnrollmentId }}", + "transferId": "{{ transferId }}", + "reservationRequestId": "{{ reservationRequestId }}", + "decisionId": "{{ riskDecisionId }}", + "decisionRequestId": "{{ riskDecisionRequestId }}", + "sourceAccountId": "{{ sourceAccountId }}", + "destinationAccountId": "{{ destinationAccountId }}", + "amount": 12500.0000, + "currency": "AED", + "policyVersion": "{{ riskPolicyVersion }}", + "correlationId": "{{ correlationId }}" +} +``` + +Expect `201 Created` with `status: "CREATED"`, an opaque `challengeId`, +`challengeStatus: "OPEN"`, `expiresAt`, `remainingAttempts`, and the bound +transfer/decision metadata. Capture `challengeId` as `mfaChallengeId`. An +exact repeated create returns `200 OK` with `Idempotent-Replay: true` and the +existing challenge; it must not create a second challenge. + +Do not change any bound field between the transfer and challenge requests. +The challenge request does not accept a customer ID override; the +authenticated JWT `sub` is bound by MFA Service. + +## 3. Verify The Transfer-Bound Challenge + +Submit the current code from the approved authenticator: + +```http +POST {{ apiGatewayUrl }}/api/v1/mfa/transfer-challenges/{{ mfaChallengeId }}/verifications +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "transferId": "{{ transferId }}", + "decisionId": "{{ riskDecisionId }}", + "code": "{{ mfaCode }}" +} +``` + +Expect `200 OK` with `status: "VERIFIED"`, +`challengeStatus: "CONSUMED"`, and the same transfer/decision binding. The +challenge is single-use. Do not send the code again after success. + +## 4. Verify Assurance And Continuation + +After the successful verification, the MFA Service writes and publishes one +`MfaAssuranceGranted.v1` fact to `mfa.assurance.granted.v1`. Inspect the +approved SIT Kafka tooling and confirm the event retains the same transfer, +reservation, decision, policy, account, amount, currency, correlation, and +challenge identifiers. The event must contain `assuranceType: "MFA"`, +`challengeType: "TOTP"`, and a future `expiresAt`. + +Then poll the existing transfer read request: + +```http +GET {{ apiGatewayUrl }}/internal/v1/transfer-workflows/{{ transferId }} +Authorization: Bearer {{ authAccessToken }} +``` + +Transaction Service must accept only a matching, unexpired assurance event. +The workflow should leave `AWAITING_STEP_UP`, return to `PENDING`, and expose +the deterministic reservation action once the assurance consumer and +reservation transport are enabled in SIT. If those event consumers are not +deployed, report the HTTP challenge verification as successful but the +continuation as unavailable; do not claim that funds were reserved. + +## Negative And Replay Checks + +| Check | Expected result | +| --- | --- | +| Missing/invalid bearer | `401` Problem Details | +| Missing MFA authorization scope | `403` Problem Details | +| Inactive or unknown enrollment | `404` or `409` Problem Details according to enrollment state | +| Transfer challenge with changed binding | `409` binding-mismatch Problem Details | +| Verification with wrong transfer or decision ID | `401` binding-mismatch or controlled verification failure | +| Wrong six-digit code | `401` invalid-code; attempts decrease | +| Expired challenge or assurance | `401` expired Problem Details; no assurance continuation | +| Replayed consumed challenge | `401` replayed Problem Details; no second assurance | +| Duplicate assurance event ID | One durable inbox/business action only | +| Malformed, mismatched, or exhausted assurance event | Quarantine/DLQ path; no reservation action | + +Never edit workflow, MFA, inbox, or outbox rows to force a result. Preserve +event IDs for retry analysis and use only the approved SIT replay procedure. + +## Evidence And Boundaries + +Record environment/date, request names, status codes, opaque identifiers, +topic/consumer observations, and redacted binding checks. Never record +passwords, bearer tokens, TOTP codes, TOTP secrets, Authorization headers, or +unredacted Kafka payloads. + +The authoritative contracts are [transfer risk and step-up](contracts/transfer-risk-step-up.md) and [MFA assurance events](contracts/mfa-assurance-events-asyncapi.yml). Implementation references are [Transaction Service PR #16](https://github.com/digital-bank-java/transaction-service/pull/16), [MFA Service PR #10](https://github.com/digital-bank-java/mfa-service/pull/10), [MFA assurance publisher PR #11](https://github.com/digital-bank-java/mfa-service/pull/11), and [Transaction assurance consumer PR #17](https://github.com/digital-bank-java/transaction-service/pull/17). This guide adds no new API or infrastructure behavior. diff --git a/docs/insomnia-transfer-workflow.md b/docs/insomnia-transfer-workflow.md new file mode 100644 index 0000000..5d19c15 --- /dev/null +++ b/docs/insomnia-transfer-workflow.md @@ -0,0 +1,179 @@ +# Insomnia Internal Transfer Workflow + +This guide exercises the internal transfer workflow through the API Gateway in +local Kubernetes SIT. It checks request validation, authorization, risk +decision metadata, idempotent replay, and observable workflow state. It does +not call downstream services directly, mutate balances, or replace automated +service and event-contract tests. + +## Current HTTP Contract + +| Method | Path | Purpose | +| --- | --- | --- | +| `POST` | `/internal/v1/transfer-workflows` | Create or idempotently replay a transfer workflow | +| `GET` | `/internal/v1/transfer-workflows/{transferId}` | Read workflow state by transfer ID | + +The request identifier is `transferId`; event contracts also refer to this +business identifier as `transactionId`. Keep all correlation and request IDs +stable for one workflow. + +The transfer risk gate runs before a reservation action is recorded. It +returns `ALLOW`, `REQUIRE_STEP_UP`, or `DECLINE`. The step-up continuation is +documented in [the step-up transfer guide](insomnia-step-up-transfer-workflow.md). + +## Preconditions And Environment + +Confirm the local SIT gateway and workloads, then keep the gateway +port-forward running: + +```bash +kubectl config use-context docker-desktop +kubectl get deployments,pods,services --namespace digital-bank-sit +kubectl port-forward --namespace digital-bank-sit service/api-gateway 8080:8080 +``` + +Use `http://localhost:8080` or the selected forwarded port. Do not port-forward +Transaction, Account, Ledger, or MFA Service directly for this workflow. + +Use a Base Environment plus `SIT`, `UAT`, and `PROD` child environments. The +Base Environment has empty placeholders only: + +```json +{ + "apiGatewayUrl": "", + "authUsername": "", + "authPassword": "", + "authAccessToken": "", + "transferId": "", + "sourceAccountId": "", + "destinationAccountId": "", + "amount": "125.5000", + "currency": "AED", + "correlationId": "", + "transferRequestId": "", + "reservationRequestId": "", + "postingRequestId": "", + "decisionRequestId": "", + "channel": "INTERNAL", + "destinationClass": "INTERNAL" +} +``` + +Set credentials, tokens, synthetic IDs, and request IDs only in private/local +values. `SIT` is the active local environment. `UAT` and `PROD` require +approved HTTPS gateway values and explicit authorization. `local` and +`LOCAL-DEV` are not supported runtime environments. + +Authenticate through the gateway using the auth/session workflow before +calling the protected transfer route. The token must have `transfer.internal` +and its `sub` must be in the configured transfer allowlist. + +## 1. Create A Transfer + +Generate fresh synthetic UUIDs and request IDs. Optional risk fields are +included below so the request matches the current risk-aware contract: + +```http +POST {{ apiGatewayUrl }}/internal/v1/transfer-workflows +Authorization: Bearer {{ authAccessToken }} +Content-Type: application/json + +{ + "transferId": "{{ transferId }}", + "sourceAccountId": "{{ sourceAccountId }}", + "destinationAccountId": "{{ destinationAccountId }}", + "amount": 125.5000, + "currency": "AED", + "correlationId": "{{ correlationId }}", + "transferRequestId": "{{ transferRequestId }}", + "reservationRequestId": "{{ reservationRequestId }}", + "postingRequestId": "{{ postingRequestId }}", + "decisionRequestId": "{{ decisionRequestId }}", + "channel": "INTERNAL", + "destinationClass": "INTERNAL" +} +``` + +`decisionRequestId`, `channel`, and `destinationClass` are optional. When +omitted, the service uses `transferRequestId`, `INTERNAL`, and `INTERNAL` as +the defaults. No `customerId`, identity claim, MFA code, or substitute +authorization header belongs in this request; the authenticated JWT subject +is the workflow customer/principal binding. + +For a normal low-risk request, expect `201 Created`, `status: "PENDING"`, a +risk decision with `riskOutcome: "ALLOW"`, and a +`REQUEST_ACCOUNT_RESERVATION` action when the event transport is enabled. +The HTTP workflow foundation may return the accepted state before downstream +reservation processing is deployed. + +The response may include `riskDecisionId`, `riskDecisionRequestId`, +`riskOutcome`, `riskReasonCodes`, `riskRequiredAssurance`, +`riskChallengeType`, `riskPolicyVersion`, `riskIssuedAt`, and `riskExpiresAt`. +Treat these as read-only decision evidence. + +## 2. Inspect The Workflow + +```http +GET {{ apiGatewayUrl }}/internal/v1/transfer-workflows/{{ transferId }} +Authorization: Bearer {{ authAccessToken }} +``` + +Expect `200 OK` for an existing workflow. Confirm the transfer IDs, request +identifiers, risk metadata, status, and actions match the test. An invalid +UUID returns `400` Problem Details; an unknown transfer returns `404`. + +## 3. Idempotent Retry And Conflict + +Resend the exact same `POST` request with the same transfer, correlation, +decision, and request identifiers. Expect `200 OK` with +`Idempotent-Replay: true`; no second workflow or reservation action is +created. + +Then change one business value, such as `amount`, while retaining the same +transfer identity. Expect `409 Conflict` with `application/problem+json`. +There is no documented `Idempotency-Key` header for this endpoint. + +## Risk Outcomes + +The default Transaction Service risk configuration requires step-up for an +amount at or above `10000` in AED or USD and for `destinationClass: +"INTERNATIONAL"`. Use the deployed SIT configuration as the authority: + +| Outcome | Expected workflow state | Reservation action | +| --- | --- | --- | +| `ALLOW` | `PENDING` | Normal reservation action may be recorded | +| `REQUIRE_STEP_UP` | `AWAITING_STEP_UP` or `PENDING` on older rollout | No reservation action until assurance | +| `DECLINE` | `FAILED` | No reservation action | + +For `REQUIRE_STEP_UP`, capture the returned risk decision fields and continue +with the step-up guide. Do not add an `mfaCode` field to this transfer request. +For `DECLINE`, verify only the HTTP state and redacted problem/evidence; do +not alter database rows to manufacture an outcome. + +## Authorization And Validation Checks + +| Check | Expected result | +| --- | --- | +| Missing, malformed, invalid, expired, or revoked bearer | `401` Problem Details | +| Valid token without `transfer.internal` or allowlisted `sub` | `403` Problem Details | +| Missing/invalid UUID or field validation failure | `400` Problem Details with `errors` | +| Source and destination account IDs equal | `400` Problem Details | +| Exact duplicate request | `200` with `Idempotent-Replay: true` | +| Same identity with changed payload | `409` Problem Details | + +## Evidence And Boundaries + +Poll only through the gateway. A transfer HTTP response or `TransferCreated.v1` +event confirms workflow acceptance, not account balance mutation. Reservation, +ledger posting, account projection, and notification evidence require their +own deployed event contracts and read-only verification procedures. + +Record only environment, date, request name, status, problem type, and opaque +IDs. Never share passwords, bearer tokens, Authorization headers, real +customer/account data, or unredacted event payloads. + +Related contracts: [transfer events](contracts/transfer-events-asyncapi.yml), +[transfer risk and step-up](contracts/transfer-risk-step-up.md), and the +[local SIT guide](local-sit.md). Gateway routing and security are in [Config +Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39) and [API +Gateway PR #23](https://github.com/digital-bank-java/api-gateway/pull/23). From 2cf069d92dae8457e82b7f1a8adc6826e1c5a5a5 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Sat, 5 Sep 2026 13:31:46 +0400 Subject: [PATCH 2/2] docs: remove duplicate Insomnia workflow patches --- README.md | 3 - docs/insomnia-auth-session-workflow.md | 122 ----------------- docs/insomnia-mfa-workflow.md | 135 ------------------- docs/insomnia-transfer-workflow.md | 179 ------------------------- 4 files changed, 439 deletions(-) delete mode 100644 docs/insomnia-auth-session-workflow.md delete mode 100644 docs/insomnia-mfa-workflow.md delete mode 100644 docs/insomnia-transfer-workflow.md diff --git a/README.md b/README.md index 694dbb6..45bda80 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,6 @@ This repository is not a deployable application. It provides shared contributor - [Reproducible local Kubernetes SIT setup and verification](docs/local-sit.md) - [Platform naming, ports, configuration, API, and infrastructure conventions](docs/platform-conventions.md) - [Workstation debugging against SIT](docs/workstation-debugging-against-sit.md) -- [Insomnia auth and session workflow](docs/insomnia-auth-session-workflow.md) -- [Insomnia MFA workflow](docs/insomnia-mfa-workflow.md) -- [Insomnia internal transfer workflow](docs/insomnia-transfer-workflow.md) - [Insomnia step-up transfer workflow](docs/insomnia-step-up-transfer-workflow.md) - [README documentation baseline](docs/readme-standard.md) diff --git a/docs/insomnia-auth-session-workflow.md b/docs/insomnia-auth-session-workflow.md deleted file mode 100644 index c233a51..0000000 --- a/docs/insomnia-auth-session-workflow.md +++ /dev/null @@ -1,122 +0,0 @@ -# Insomnia Auth And Session Workflow - -This guide is a repeatable manual check of authentication and server-side -session behavior through the API Gateway in local Kubernetes SIT. It does not -replace Auth Service tests, gateway tests, or deployment checks. - -## Preconditions - -Confirm the local SIT cluster, Auth Service, and API Gateway are healthy: - -```bash -kubectl config use-context docker-desktop -kubectl get deployments,pods,services --namespace digital-bank-sit -kubectl port-forward --namespace digital-bank-sit service/api-gateway 8080:8080 -``` - -Use `http://localhost:8080` as the workstation gateway URL, or the selected -forwarded port if `8080` is occupied. Use the gateway for every request in -this guide; do not add a direct Auth Service URL to the shared environment. - -## Environment - -Use one Insomnia workspace with a Base Environment and named `SIT`, `UAT`, -and `PROD` child environments. The Base Environment contains names and empty -placeholders only: - -```json -{ - "apiGatewayUrl": "", - "authUsername": "", - "authPassword": "", - "authAccessToken": "", - "authSessionId": "" -} -``` - -Keep usernames, passwords, bearer tokens, and session IDs in private/local -values. Do not export or sync those values. `SIT` is the active local -environment; `UAT` and `PROD` require approved gateway URLs and test -identities. `local` and `LOCAL-DEV` are not supported environments. - -## Login - -Select `SIT` and send: - -```http -POST {{ apiGatewayUrl }}/api/v1/auth/login -Content-Type: application/json - -{ - "username": "{{ authUsername }}", - "password": "{{ authPassword }}" -} -``` - -Expect `200 OK` with `accessToken`, `tokenType: "Bearer"`, `sessionId`, and -`expiresAt`. The signed JWT contains `sub`, `sid`, `active`, `iss`, `iat`, and -`exp`, plus the configured space-delimited `scope` claim. The JWT `sid` must -match the response `sessionId`. Store only the token and session ID in private -local values. - -With the default `REVOKE_PREVIOUS` session policy, a second successful login -for the same username revokes the earlier active session. The newest token -remains usable and the earlier token must fail once server-side session -validation is enforced. - -## Protected Session Check - -Use an already-defined protected request from the service workflow under test, -for example the transfer read request in -[the internal transfer guide](insomnia-transfer-workflow.md): - -```http -GET {{ apiGatewayUrl }}/internal/v1/transfer-workflows/{{ transferId }} -Authorization: Bearer {{ authAccessToken }} -``` - -Do not invent a placeholder endpoint merely to test authentication. A -successful protected response confirms the gateway accepted the bearer token -and the server-side session is active for that route. Then repeat the same -request with these controlled variations: - -1. Remove the `Authorization` header. Expect `401 Unauthorized`. -2. Change one character in the token. Expect `401 Unauthorized`. -3. Log out, then repeat the request with the same token. Expect `401 - Unauthorized` after revocation enforcement is deployed. - -## Logout And Revocation - -Send: - -```http -POST {{ apiGatewayUrl }}/api/v1/auth/logout -Authorization: Bearer {{ authAccessToken }} -``` - -Expect `204 No Content`. Repeat the request with the same valid token shape; -logout is idempotent and should return `204` again. Repeat the protected -request and confirm that the revoked session is rejected. Clear the private -token and session values after the check. - -## Failure Checks - -| Check | Expected result | -| --- | --- | -| Blank or malformed login payload | `400` `application/problem+json` with validation errors | -| Unknown username or wrong password | `401` authentication-failed Problem Details | -| Missing, malformed, invalid, expired, or revoked bearer | `401` invalid-token Problem Details | -| Repeated logout with a valid token | `204 No Content` | -| Gateway route unavailable or returns `404` | Check gateway/configuration rollout; do not bypass the gateway | - -Never record passwords, raw JWTs, Authorization headers, customer data, or -private environment values in issues, PRs, screenshots, or logs. Share only -redacted status codes, problem types, and opaque identifiers. - -## Dependencies And Boundaries - -The auth/session implementation is in [Auth Service PR #7](https://github.com/digital-bank-java/auth-service/pull/7), with the JWT/session foundation in [PRs #2-#6](https://github.com/digital-bank-java/auth-service/pulls?q=is%3Apr+is%3Amerged). Gateway route and scope enforcement are in [API Gateway PR #23](https://github.com/digital-bank-java/api-gateway/pull/23) and [Config Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39). Use the workflow only after the relevant service, configuration, and gateway revisions are deployed in SIT. - -The current Auth Service API intentionally provides login and logout only. It -does not expose a public session-introspection or refresh endpoint, so no such -request is included here. diff --git a/docs/insomnia-mfa-workflow.md b/docs/insomnia-mfa-workflow.md deleted file mode 100644 index acd784e..0000000 --- a/docs/insomnia-mfa-workflow.md +++ /dev/null @@ -1,135 +0,0 @@ -# Insomnia MFA Workflow - -This guide verifies the generic MFA enrollment and challenge lifecycle through -the API Gateway. Use synthetic SIT identities only. The transfer-bound -step-up flow is documented separately in -[the step-up transfer guide](insomnia-step-up-transfer-workflow.md). - -## Preconditions And Environment - -The API Gateway port-forward, MFA Service, Auth Service, and the gateway MFA -route must be healthy. The route/configuration dependency is [Config Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39). - -Use the shared Insomnia Base Environment and select `SIT`: - -| Variable | Purpose | -| --- | --- | -| `apiGatewayUrl` | API Gateway port-forward, normally `http://localhost:8080` | -| `authAccessToken` | Private internal JWT with the configured MFA scope | -| `mfaEnrollmentId` | Opaque enrollment ID captured from creation | -| `mfaChallengeId` | Opaque challenge ID captured from creation | -| `mfaCode` | Private six-digit code from the approved authenticator | - -Keep all credentials, tokens, codes, and identifiers in private/local values. -Do not add a direct MFA Service URL to a shared environment. - -Every authenticated request uses: - -```http -Authorization: Bearer {{ authAccessToken }} -``` - -## 1. Create Enrollment - -Enrollment ownership is derived from the authenticated JWT `sub` claim. The -legacy `subjectId` field is accepted for compatibility but ignored, so do not -add it to a new request: - -```http -POST {{ apiGatewayUrl }}/api/v1/mfa/enrollments -Authorization: Bearer {{ authAccessToken }} -Content-Type: application/json - -{} -``` - -Expect `201 Created` with an opaque `enrollmentId`, `status: "ENROLLED"`, and -`enrollmentStatus: "PENDING"`. Capture the ID as `mfaEnrollmentId`. The -response must not contain a TOTP secret or provisioning URI. - -The current service contract does not expose a secret/provisioning response. -An approved platform authenticator path must provision the enrollment before -the next request can succeed. Do not guess a code or add a secret field. - -## 2. Verify Enrollment - -After the approved authenticator path supplies a valid code, send: - -```http -POST {{ apiGatewayUrl }}/api/v1/mfa/enrollments/{{ mfaEnrollmentId }}/verifications -Authorization: Bearer {{ authAccessToken }} -Content-Type: application/json - -{ - "code": "{{ mfaCode }}" -} -``` - -Expect `200 OK` with `status: "ACTIVATED"` and -`enrollmentStatus: "ACTIVE"`. A wrong six-digit code returns `401` Problem -Details; an unknown or foreign enrollment returns `404`; an already active -enrollment returns `409`. - -## 3. Create Challenge - -Once the enrollment is active, send: - -```http -POST {{ apiGatewayUrl }}/api/v1/mfa/challenges -Authorization: Bearer {{ authAccessToken }} -Content-Type: application/json - -{ - "enrollmentId": "{{ mfaEnrollmentId }}" -} -``` - -Expect `201 Created` with an opaque `challengeId`, -`challengeStatus: "OPEN"`, `expiresAt`, and `remainingAttempts`. Capture the -ID as `mfaChallengeId`. - -## 4. Verify Challenge - -Submit the current code: - -```http -POST {{ apiGatewayUrl }}/api/v1/mfa/challenges/{{ mfaChallengeId }}/verifications -Authorization: Bearer {{ authAccessToken }} -Content-Type: application/json - -{ - "code": "{{ mfaCode }}" -} -``` - -Expect `200 OK` with `status: "VERIFIED"` and -`challengeStatus: "CONSUMED"`. The challenge is single-use. - -## Negative Checks - -| Check | Expected result | -| --- | --- | -| Missing, malformed, expired, or revoked bearer | `401` `application/problem+json` | -| Authenticated principal without the MFA scope | `403` `application/problem+json` | -| Non-six-digit verification code | `400` validation Problem Details | -| Unknown or foreign enrollment/challenge | `404` resource-not-found Problem Details | -| Wrong six-digit code | `401` invalid-code Problem Details; attempts decrease | -| Expired challenge | `401` challenge-expired Problem Details | -| Exhausted challenge | `401` challenge-exhausted Problem Details | -| Replayed consumed challenge | `401` challenge-replayed Problem Details | -| Challenge created before enrollment is active | `409` enrollment-not-active Problem Details | - -The MFA Service also enforces authenticated-principal ownership. Do not use a -different JWT subject to access an existing enrollment or challenge. - -## Evidence And Boundaries - -Record only the environment, date, request names, status codes, redacted -problem types, and opaque IDs where policy permits. Never record bearer -tokens, submitted codes, TOTP secrets, provisioning material, or raw response -dumps. - -This generic workflow does not authorize a transfer, mutate account balances, -or publish transfer assurance. Successful transfer-bound verification and its -event handoff are covered by the separate step-up guide. The MFA Service has -no customer login, session management, recovery-code, or direct account API. diff --git a/docs/insomnia-transfer-workflow.md b/docs/insomnia-transfer-workflow.md deleted file mode 100644 index 5d19c15..0000000 --- a/docs/insomnia-transfer-workflow.md +++ /dev/null @@ -1,179 +0,0 @@ -# Insomnia Internal Transfer Workflow - -This guide exercises the internal transfer workflow through the API Gateway in -local Kubernetes SIT. It checks request validation, authorization, risk -decision metadata, idempotent replay, and observable workflow state. It does -not call downstream services directly, mutate balances, or replace automated -service and event-contract tests. - -## Current HTTP Contract - -| Method | Path | Purpose | -| --- | --- | --- | -| `POST` | `/internal/v1/transfer-workflows` | Create or idempotently replay a transfer workflow | -| `GET` | `/internal/v1/transfer-workflows/{transferId}` | Read workflow state by transfer ID | - -The request identifier is `transferId`; event contracts also refer to this -business identifier as `transactionId`. Keep all correlation and request IDs -stable for one workflow. - -The transfer risk gate runs before a reservation action is recorded. It -returns `ALLOW`, `REQUIRE_STEP_UP`, or `DECLINE`. The step-up continuation is -documented in [the step-up transfer guide](insomnia-step-up-transfer-workflow.md). - -## Preconditions And Environment - -Confirm the local SIT gateway and workloads, then keep the gateway -port-forward running: - -```bash -kubectl config use-context docker-desktop -kubectl get deployments,pods,services --namespace digital-bank-sit -kubectl port-forward --namespace digital-bank-sit service/api-gateway 8080:8080 -``` - -Use `http://localhost:8080` or the selected forwarded port. Do not port-forward -Transaction, Account, Ledger, or MFA Service directly for this workflow. - -Use a Base Environment plus `SIT`, `UAT`, and `PROD` child environments. The -Base Environment has empty placeholders only: - -```json -{ - "apiGatewayUrl": "", - "authUsername": "", - "authPassword": "", - "authAccessToken": "", - "transferId": "", - "sourceAccountId": "", - "destinationAccountId": "", - "amount": "125.5000", - "currency": "AED", - "correlationId": "", - "transferRequestId": "", - "reservationRequestId": "", - "postingRequestId": "", - "decisionRequestId": "", - "channel": "INTERNAL", - "destinationClass": "INTERNAL" -} -``` - -Set credentials, tokens, synthetic IDs, and request IDs only in private/local -values. `SIT` is the active local environment. `UAT` and `PROD` require -approved HTTPS gateway values and explicit authorization. `local` and -`LOCAL-DEV` are not supported runtime environments. - -Authenticate through the gateway using the auth/session workflow before -calling the protected transfer route. The token must have `transfer.internal` -and its `sub` must be in the configured transfer allowlist. - -## 1. Create A Transfer - -Generate fresh synthetic UUIDs and request IDs. Optional risk fields are -included below so the request matches the current risk-aware contract: - -```http -POST {{ apiGatewayUrl }}/internal/v1/transfer-workflows -Authorization: Bearer {{ authAccessToken }} -Content-Type: application/json - -{ - "transferId": "{{ transferId }}", - "sourceAccountId": "{{ sourceAccountId }}", - "destinationAccountId": "{{ destinationAccountId }}", - "amount": 125.5000, - "currency": "AED", - "correlationId": "{{ correlationId }}", - "transferRequestId": "{{ transferRequestId }}", - "reservationRequestId": "{{ reservationRequestId }}", - "postingRequestId": "{{ postingRequestId }}", - "decisionRequestId": "{{ decisionRequestId }}", - "channel": "INTERNAL", - "destinationClass": "INTERNAL" -} -``` - -`decisionRequestId`, `channel`, and `destinationClass` are optional. When -omitted, the service uses `transferRequestId`, `INTERNAL`, and `INTERNAL` as -the defaults. No `customerId`, identity claim, MFA code, or substitute -authorization header belongs in this request; the authenticated JWT subject -is the workflow customer/principal binding. - -For a normal low-risk request, expect `201 Created`, `status: "PENDING"`, a -risk decision with `riskOutcome: "ALLOW"`, and a -`REQUEST_ACCOUNT_RESERVATION` action when the event transport is enabled. -The HTTP workflow foundation may return the accepted state before downstream -reservation processing is deployed. - -The response may include `riskDecisionId`, `riskDecisionRequestId`, -`riskOutcome`, `riskReasonCodes`, `riskRequiredAssurance`, -`riskChallengeType`, `riskPolicyVersion`, `riskIssuedAt`, and `riskExpiresAt`. -Treat these as read-only decision evidence. - -## 2. Inspect The Workflow - -```http -GET {{ apiGatewayUrl }}/internal/v1/transfer-workflows/{{ transferId }} -Authorization: Bearer {{ authAccessToken }} -``` - -Expect `200 OK` for an existing workflow. Confirm the transfer IDs, request -identifiers, risk metadata, status, and actions match the test. An invalid -UUID returns `400` Problem Details; an unknown transfer returns `404`. - -## 3. Idempotent Retry And Conflict - -Resend the exact same `POST` request with the same transfer, correlation, -decision, and request identifiers. Expect `200 OK` with -`Idempotent-Replay: true`; no second workflow or reservation action is -created. - -Then change one business value, such as `amount`, while retaining the same -transfer identity. Expect `409 Conflict` with `application/problem+json`. -There is no documented `Idempotency-Key` header for this endpoint. - -## Risk Outcomes - -The default Transaction Service risk configuration requires step-up for an -amount at or above `10000` in AED or USD and for `destinationClass: -"INTERNATIONAL"`. Use the deployed SIT configuration as the authority: - -| Outcome | Expected workflow state | Reservation action | -| --- | --- | --- | -| `ALLOW` | `PENDING` | Normal reservation action may be recorded | -| `REQUIRE_STEP_UP` | `AWAITING_STEP_UP` or `PENDING` on older rollout | No reservation action until assurance | -| `DECLINE` | `FAILED` | No reservation action | - -For `REQUIRE_STEP_UP`, capture the returned risk decision fields and continue -with the step-up guide. Do not add an `mfaCode` field to this transfer request. -For `DECLINE`, verify only the HTTP state and redacted problem/evidence; do -not alter database rows to manufacture an outcome. - -## Authorization And Validation Checks - -| Check | Expected result | -| --- | --- | -| Missing, malformed, invalid, expired, or revoked bearer | `401` Problem Details | -| Valid token without `transfer.internal` or allowlisted `sub` | `403` Problem Details | -| Missing/invalid UUID or field validation failure | `400` Problem Details with `errors` | -| Source and destination account IDs equal | `400` Problem Details | -| Exact duplicate request | `200` with `Idempotent-Replay: true` | -| Same identity with changed payload | `409` Problem Details | - -## Evidence And Boundaries - -Poll only through the gateway. A transfer HTTP response or `TransferCreated.v1` -event confirms workflow acceptance, not account balance mutation. Reservation, -ledger posting, account projection, and notification evidence require their -own deployed event contracts and read-only verification procedures. - -Record only environment, date, request name, status, problem type, and opaque -IDs. Never share passwords, bearer tokens, Authorization headers, real -customer/account data, or unredacted event payloads. - -Related contracts: [transfer events](contracts/transfer-events-asyncapi.yml), -[transfer risk and step-up](contracts/transfer-risk-step-up.md), and the -[local SIT guide](local-sit.md). Gateway routing and security are in [Config -Repo PR #39](https://github.com/digital-bank-java/config-repo/pull/39) and [API -Gateway PR #23](https://github.com/digital-bank-java/api-gateway/pull/23).