feature: replace the endpoint auth mode UserOrApplication with

UserXORApplication: a request is either a person acting on their own
Entitlements or an application acting as itself (no User, or its own
obp-oidc#client client-credentials User) on its Consumer's Scopes, never
a mix, so a person calling through a Consumer no longer gets its Scopes
and who is let in is who is recorded as acting. The require_scopes props
no longer make an application acting as itself also need Entitlements.
Dynamic Entity auth_mode still accepts UserOrApplication and stores it
as UserXORApplication
+ feature: v7.0.0 Open Corridor attach promise evidence, settlement, fee
  settlement and get settlement are UserXORApplication, so a bank's Bank
  Node can call them as itself with a client-credentials token
+ feature: add Files to v7.0.0: store a document or photograph in a
  space (POST /banks/BANK_ID/files, base64 in JSON, Role
  CanCreateFileAtOneBank, or a Role at SYS for the system space, no
  AtAnyBank Roles), read it, its content and its attachments as owner, a
  User given access or with CanGetFileAtOneBank, attach it to records,
  share it, and make it public with CanCreatePublicFileAtOneBank. Public
  files are served without login by separate public-files endpoints that
  serve nothing else. Media types are at most jpeg, png, webp and pdf,
  and the content must match its type
+ fix: Make sure that file content responses keep their own Content-Type
  and send nosniff and a sandbox Content-Security-Policy, and that file
  bytes can be stored on H2

Author: simonredfern

obp-api/src/main/resources/docs/introductory_system_documentation.md

@@ -139,7 +139,7 @@ The Open Bank Project (OBP) is an open-source RESTful API platform for banks tha
 - **Views System**: Account data visibility control (owner, public, accountant, auditor, custom)
 - **Scope Management**: OAuth 2.0 scope definitions
 - **Authentication Type Validation**: Enforce authentication requirements per endpoint
-- **Endpoint Auth Modes**: Per-endpoint control over user vs application authentication (UserOnly, ApplicationOnly, UserOrApplication, UserAndApplication)
+- **Endpoint Auth Modes**: Per-endpoint control over user vs application authentication (UserOnly, ApplicationOnly, UserXORApplication, UserAndApplication)
 - **Mandates**: Corporate account governance with provisions, signatory panels, and multi-signature approval
 
 #### 1.2.9 Extensibility & Customization
@@ -2699,7 +2699,7 @@ OBP can bootstrap a Consumer (Application) for OBP-OIDC at startup. This allows
 
 The bootstrap consumer is granted the following Scopes: `CanGetConsumers`, `CanCreateConsumer`, `CanVerifyOidcClient`, `CanGetOidcClient`, `CanGetOidcConsent`.
 
-These endpoints use `authMode = UserOrApplication`, meaning they can be accessed either by a logged-in User with Entitlements, or by an Application using a Consumer Key with Scopes.
+These endpoints use `authMode = UserXORApplication`, meaning they can be accessed either by a logged-in User with Entitlements, or by the Application acting as itself (e.g. with a client-credentials token) with its Consumer's Scopes. A User calling through the Consumer does not get its Scopes.
 
 ```properties
 # Bootstrap OIDC Operator Consumer
@@ -3022,18 +3022,18 @@ Previously, a global `allow_entitlements_or_scopes` config flag allowed consumer
 |------|-------------|
 | `UserOnly` | (Default) Requires user authentication and user entitlements |
 | `ApplicationOnly` | Requires consumer scope only, no user authentication needed |
-| `UserOrApplication` | Either consumer scope OR user entitlement is sufficient |
+| `UserXORApplication` | Consumer scope when the application acts as itself (no user, or its own client-credentials user, provider `obp-oidc#client`); user entitlement when a person acts. A person never uses the consumer's scopes. Formerly `UserOrApplication` (either was sufficient) |
 | `UserAndApplication` | Both consumer scope AND user entitlement are required |
 
 **Migration from `allow_entitlements_or_scopes`:**
 
-The global `allow_entitlements_or_scopes` config flag has been removed. Deployments that previously used `allow_entitlements_or_scopes=true` must now set `authMode = UserOrApplication` on individual endpoint `ResourceDoc` instances.
+The global `allow_entitlements_or_scopes` config flag has been removed. Deployments that previously used `allow_entitlements_or_scopes=true` must now set `authMode = UserXORApplication` on individual endpoint `ResourceDoc` instances.
 
-The global overrides `require_scopes_for_all_roles` and `require_scopes_for_listed_roles` continue to work and force `UserAndApplication` behavior.
+The global overrides `require_scopes_for_all_roles` and `require_scopes_for_listed_roles` continue to work and force `UserAndApplication` behavior, except for an application acting as itself on an `ApplicationOnly` or `UserXORApplication` endpoint, which still needs only its scopes.
 
 **Example:**
 
-The `verifyUserCredentials` endpoint uses `UserOrApplication` mode, so it can be called either by a logged-in user with the appropriate entitlement, or by an application with the appropriate consumer scope.
+The `verifyUserCredentials` endpoint uses `UserXORApplication` mode, so it can be called either by a logged-in user with the appropriate entitlement, or by an application acting as itself with the appropriate consumer scope.
 
 ### 8.8 Maker/Checker for Transaction Requests
 
@@ -4298,7 +4298,7 @@ docker run -p 8080:8080 \
 
 **Dynamic Endpoint:** User-defined API endpoint
 
-**Endpoint Auth Mode:** Per-endpoint setting controlling whether user authentication, application scope, or both are required (UserOnly, ApplicationOnly, UserOrApplication, UserAndApplication)
+**Endpoint Auth Mode:** Per-endpoint setting controlling whether user authentication, application scope, or both are required (UserOnly, ApplicationOnly, UserXORApplication, UserAndApplication)
 
 **Entitlement:** Permission to perform specific operation (same as Role)
 

obp-api/src/main/scala/code/api/ResourceDocs1_4_0/OpenAPI31JSONFactory.scala

@@ -168,7 +168,7 @@ object OpenAPI31JSONFactory extends MdcLoggable {
        |
        |### Client Credentials Flow (2-legged / Application Only)
        |
-       |Use this flow for endpoints with authMode ApplicationOnly or UserOrApplication.
+       |Use this flow for endpoints with authMode ApplicationOnly or UserXORApplication.
        |The application authenticates itself using its client_id and client_secret without a user login.
        |
        |    POST $oidcTokenEndpoint

obp-api/src/main/scala/code/api/UKOpenBanking/v3_1_0/Http4sUKOBv310AccountAccess.scala

@@ -32,7 +32,7 @@ import cats.data.{Kleisli, OptionT}
 import cats.effect.IO
 import code.api.Constant
 import code.api.UKOpenBanking.v3_1_0.JSONFactory_UKOpenBanking_310.ConsentPostBodyUKV310
-import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, UserOrApplication, connectorEmptyResponse, mockedDataText, passesPsd2Aisp, unboxFullOrFail, parseIso8601OrDayDate}
+import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, UserXORApplication, connectorEmptyResponse, mockedDataText, passesPsd2Aisp, unboxFullOrFail, parseIso8601OrDayDate}
 import code.api.util.ApiTag
 import code.api.util.CustomJsonFormats
 import code.api.util.ErrorMessages.{AuthenticatedUserIsRequired, ConsentNotFound, ConsentViewNotFund, InvalidJsonFormat, InvalidUKConsentPermissions, UnknownError}
@@ -201,8 +201,8 @@ object Http4sUKOBv310AccountAccess extends MdcLoggable {
     // Without it the doc defaults to UserOnly, which sends the middleware down anonymousAccess and
     // 401s any request that carries no user -- so the endpoint only works today because OAuth2
     // token parsing auto-vivifies a user for a client-credentials token. Matches the Berlin Group
-    // twin (Http4sBGv13AIS.createConsent), which has always been UserOrApplication.
-    authMode = UserOrApplication,
+    // twin (Http4sBGv13AIS.createConsent), which has always been UserXORApplication.
+    authMode = UserXORApplication,
     http4sPartialFunction = Some(createAccountAccessConsents)
   )
 
@@ -239,7 +239,7 @@ object Http4sUKOBv310AccountAccess extends MdcLoggable {
     ApiTag("Account Access") :: Nil,
     // As with the POST that lodges the consent: revoking is a client-credentials call in the
     // standard's AISP flow, so a PSU cannot be required. See Consent.checkUKConsentAccess.
-    authMode = UserOrApplication,
+    authMode = UserXORApplication,
     http4sPartialFunction = Some(deleteAccountAccessConsentsConsentId)
   )
 
@@ -317,7 +317,7 @@ object Http4sUKOBv310AccountAccess extends MdcLoggable {
     List(AuthenticatedUserIsRequired, UnknownError),
     ApiTag("Account Access") :: Nil,
     // As above: the AISP polls its own consent with a client-credentials token.
-    authMode = UserOrApplication,
+    authMode = UserXORApplication,
     http4sPartialFunction = Some(getAccountAccessConsentsConsentId)
   )
 

obp-api/src/main/scala/code/api/UKOpenBanking/v4_0_1/Http4sUKOBv401AccountInfo.scala

@@ -34,7 +34,7 @@ import cats.effect.IO
 import code.api.APIFailureNewStyle
 import code.api.Constant
 import code.api.UKOpenBanking.v3_1_0.JSONFactory_UKOpenBanking_310.ConsentPostBodyUKV310
-import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, HTTPParam, UserOrApplication, connectorEmptyResponse, createQueriesByHttpParams, defaultBankId, fullBoxOrException, passesPsd2Aisp, unboxFull, unboxFullOrFail, parseIso8601OrDayDate}
+import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, HTTPParam, UserXORApplication, connectorEmptyResponse, createQueriesByHttpParams, defaultBankId, fullBoxOrException, passesPsd2Aisp, unboxFull, unboxFullOrFail, parseIso8601OrDayDate}
 import code.api.util.ApiTag
 import code.api.util.CallContext
 import code.api.util.CustomJsonFormats
@@ -209,8 +209,8 @@ object Http4sUKOBv401AccountInfo extends MdcLoggable {
     // Without it the doc defaults to UserOnly, which sends the middleware down anonymousAccess and
     // 401s any request that carries no user -- so the endpoint only works today because OAuth2
     // token parsing auto-vivifies a user for a client-credentials token. Matches the Berlin Group
-    // twin (Http4sBGv13AIS.createConsent), which has always been UserOrApplication.
-    authMode = UserOrApplication,
+    // twin (Http4sBGv13AIS.createConsent), which has always been UserXORApplication.
+    authMode = UserXORApplication,
     http4sPartialFunction = Some(createAccountAccessConsents)
   )
 
@@ -290,7 +290,7 @@ object Http4sUKOBv401AccountInfo extends MdcLoggable {
     ApiTag("Account Access Consents") :: Nil,
     // Same reasoning as the POST that lodges the consent: the AISP polls it with a
     // client-credentials token, so a PSU cannot be required. See Consent.checkUKConsentAccess.
-    authMode = UserOrApplication,
+    authMode = UserXORApplication,
     http4sPartialFunction = Some(getAccountAccessConsentsConsentId)
   )
 
@@ -323,7 +323,7 @@ object Http4sUKOBv401AccountInfo extends MdcLoggable {
     List(AuthenticatedUserIsRequired, UnknownError),
     ApiTag("Account Access Consents") :: Nil,
     // As above: revoking is a client-credentials call in the standard's AISP flow.
-    authMode = UserOrApplication,
+    authMode = UserXORApplication,
     http4sPartialFunction = Some(deleteAccountAccessConsentsConsentId)
   )
 

obp-api/src/main/scala/code/api/berlin/group/v1_3/Http4sBGv13AIS.scala

@@ -38,7 +38,7 @@ import code.api.berlin.group.v1_3.model._
 import code.api.berlin.group.v1_3.{BgSpecValidation, JSONFactory_BERLIN_GROUP_1_3, JvalueCaseClass}
 import code.api.RequestHeader
 import code.api.util.APIUtil
-import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, UserOrApplication, connectorEmptyResponse, createQueriesByHttpParams, fullBoxOrException, getHttpRequestUrlParam, getSuggestedDefaultScaMethod, mockedDataText, passesPsd2Aisp, unboxFull, unboxFullOrFail}
+import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, UserXORApplication, connectorEmptyResponse, createQueriesByHttpParams, fullBoxOrException, getHttpRequestUrlParam, getSuggestedDefaultScaMethod, mockedDataText, passesPsd2Aisp, unboxFull, unboxFullOrFail}
 import code.api.util.CallContext
 import code.api.util.ApiTag._
 import code.api.util.CustomJsonFormats
@@ -847,7 +847,7 @@ recurringIndicator:
       ),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(createConsent)
     )
 
@@ -863,7 +863,7 @@ recurringIndicator:
       EmptyBody,
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(deleteConsent)
     )
 
@@ -901,7 +901,7 @@ where the consent was directly managed between ASPSP and PSU e.g. in a re-direct
                   }""")),
       List(AuthenticatedUserIsRequired, ConsentNotFound, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(getConsentInformation)
     )
 
@@ -919,7 +919,7 @@ where the consent was directly managed between ASPSP and PSU e.g. in a re-direct
                    }""")),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(getConsentStatus)
     )
 
@@ -980,7 +980,7 @@ using the extended forms as indicated above.
       // so the doc can now say what the call actually is, as its GET siblings already do. Left on
       // the UserOnly default it would 401 a client-credentials caller the day OAuth2 token parsing
       // stops auto-vivifying a user.
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(startConsentAuthorisationAll)
     )
 
@@ -995,7 +995,7 @@ using the extended forms as indicated above.
       startConsentAuthorisationResponse,
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(startConsentAuthorisationAll)
     )
 
@@ -1010,7 +1010,7 @@ using the extended forms as indicated above.
       startConsentAuthorisationResponse,
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(startConsentAuthorisationAll)
     )
 
@@ -1057,7 +1057,7 @@ Maybe in a later version the access path will change.
       ),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(updateConsentsPsuDataAll)
     )
 
@@ -1077,7 +1077,7 @@ Maybe in a later version the access path will change.
          |        }""".stripMargin)),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(updateConsentsPsuDataAll)
     )
 
@@ -1105,7 +1105,7 @@ Maybe in a later version the access path will change.
                    |        }""".stripMargin)),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(updateConsentsPsuDataAll)
     )
 
@@ -1125,7 +1125,7 @@ Maybe in a later version the access path will change.
                    |        }""".stripMargin)),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(updateConsentsPsuDataAll)
     )
   }
@@ -1347,8 +1347,8 @@ This function returns an array of hyperlinks to all generated authorisation sub-
       // Embedded. The handler already reflects that, taking no user; only the doc disagreed, and a
       // doc left on the UserOnly default sends the middleware down anonymousAccess, which 401s a
       // request carrying no user. Brings these into line with the consent endpoints in this same
-      // file, which have been UserOrApplication all along.
-      authMode = UserOrApplication,
+      // file, which have been UserXORApplication all along.
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(getConsentAuthorisation)
     )
 
@@ -1368,7 +1368,7 @@ This method returns the SCA status of a consent initiation's authorisation sub-r
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Account Information Service (AIS)") :: apiTagBerlinGroupM :: Nil,
       // As above -- reading the SCA status is the TPP polling its own authorisation sub-resource.
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(getConsentScaStatus)
     )
 

obp-api/src/main/scala/code/api/berlin/group/v1_3/Http4sBGv13PIS.scala

@@ -34,7 +34,7 @@ import code.api.berlin.group.ConstantsBG
 import code.api.berlin.group.v1_3.JSONFactory_BERLIN_GROUP_1_3._
 import code.api.berlin.group.v1_3.model.TransactionStatus.mapTransactionStatus
 import code.api.berlin.group.v1_3.model._
-import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, UserOrApplication, getScaMethodAtInstance, getServerUrl, isValidCurrencyISOCode, mockedDataText, passesPsd2Pisp}
+import code.api.util.APIUtil.{Http4sHandler, Http4sRoute, EmptyBody, ResourceDoc, UserXORApplication, getScaMethodAtInstance, getServerUrl, isValidCurrencyISOCode, mockedDataText, passesPsd2Pisp}
 import code.api.util.ApiTag._
 import code.api.util.ErrorMessages._
 import code.api.util.CustomJsonFormats
@@ -143,7 +143,7 @@ object Http4sBGv13PIS extends MdcLoggable {
   /**
    * Shared business logic for all three initiate-payment variants (payments / periodic-payments /
    * bulk-payments). Mirrors `initiatePaymentImplementation` from the Lift builder; auth is handled
-   * by middleware (authMode = UserOrApplication), so no inline applicationAccess call.
+   * by middleware (authMode = UserXORApplication), so no inline applicationAccess call.
    */
   private def initiatePaymentImpl(
     paymentService: String,
@@ -427,7 +427,7 @@ object Http4sBGv13PIS extends MdcLoggable {
   }
 
   // ── POST /payments/{paymentProduct} ──────────────────────────────────────────────────────────────
-  // Auth: applicationAccess in Lift → authMode = UserOrApplication in ResourceDoc
+  // Auth: applicationAccess in Lift → authMode = UserXORApplication in ResourceDoc
   lazy val initiatePayments: Http4sRoute = Http4sRoute {
     case req @ POST -> `bgV13Prefix` / "payments" / paymentProduct =>
       EndpointHelpers.executeFutureCreated(req) {
@@ -1042,7 +1042,7 @@ $generalPaymentSummaryText""",
       initiatePaymentResponseBody,
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Payment Initiation Service (PIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(initiatePayments)
     )
 
@@ -1075,7 +1075,7 @@ $generalPaymentSummaryText""",
       }""")),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Payment Initiation Service (PIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(initiatePeriodicPayments)
     )
 
@@ -1111,7 +1111,7 @@ $generalPaymentSummaryText""",
       }""")),
       List(AuthenticatedUserIsRequired, UnknownError),
       ApiTag("Payment Initiation Service (PIS)") :: apiTagBerlinGroupM :: Nil,
-      authMode = UserOrApplication,
+      authMode = UserXORApplication,
       http4sPartialFunction = Some(initiateBulkPayments)
     )
   }

obp-api/src/main/scala/code/api/dynamic/entity/Http4sDynamicEntity.scala

@@ -343,7 +343,7 @@ object Http4sDynamicEntity extends MdcLoggable {
   private def entityAccess(cc: CallContext, bankId: Option[String], entityName: String, isPersonalEntity: Boolean): Future[(Box[User], Option[CallContext])] =
     if (isPersonalEntity || isRowLevel(bankId, entityName)) authenticatedAccess(cc)
     else authModeOf(bankId, entityName) match {
-      case ApplicationOnly | UserOrApplication => applicationAccess(cc)
+      case ApplicationOnly | UserXORApplication => applicationAccess(cc)
       case _ => authenticatedAccess(cc)
     }
 

obp-api/src/main/scala/code/api/dynamic/entity/helper/DynamicEntityHelper.scala

@@ -1081,7 +1081,8 @@ case class DynamicEntityInfo(definition: String, entityName: String, bankId: Opt
   /** The entity's auth mode as the framework type; unknown or empty values read as UserOnly. */
   val endpointAuthMode: code.api.util.APIUtil.EndpointAuthMode = authMode match {
     case code.dynamicEntity.DynamicEntityAuthMode.ApplicationOnly => code.api.util.APIUtil.ApplicationOnly
-    case code.dynamicEntity.DynamicEntityAuthMode.UserOrApplication => code.api.util.APIUtil.UserOrApplication
+    case code.dynamicEntity.DynamicEntityAuthMode.UserXORApplication | code.dynamicEntity.DynamicEntityAuthMode.LegacyUserOrApplication =>
+      code.api.util.APIUtil.UserXORApplication
     case code.dynamicEntity.DynamicEntityAuthMode.UserAndApplication => code.api.util.APIUtil.UserAndApplication
     case _ => code.api.util.APIUtil.UserOnly
   }