Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ For more detailed information or the sources of truths, please refer to the indi
- 3.13 [OBP-MCP (Model Context Protocol Server)](#313-obp-mcp-model-context-protocol-server)
- 3.14 [OBP-Sentinel](#314-obp-sentinel)
- 3.15 [OBP Bank Node](#315-obp-bank-node)
- 3.16 [OBP Cohort](#316-obp-cohort)
- 3.17 [Conformator](#317-conformator)
4. [Standards Compliance](#standards-compliance)
5. [Installation and Configuration](#installation-and-configuration)
6. [Migration Scripts and Migration Script Logs](#migration-scripts-and-migration-script-logs)
Expand Down Expand Up @@ -236,8 +238,10 @@ The Open Bank Project (OBP) is an open-source RESTful API platform for banks tha
- **Keycloak Integration:** Production-grade OIDC provider support
- **OBP Portal:** Developer portal where people sign up, register applications and try the API
- **OBP-MCP:** Model Context Protocol server, so AI agents can find and call OBP endpoints
- **OBP-Sentinel:** Watches running OBP instances and suggests the improvements that matter most
- **OBP-Sentinel (OBP Senti):** Watches running OBP instances and suggests the improvements that matter most
- **OBP Bank Node:** Runs inside a bank's network and connects its core banking system to an OBP instance run by a platform operator
- **OBP Cohort:** Runs startup programmes, from the call for applications to graduation
- **Conformator:** Tests open banking APIs against the agreed standard and issues signed conformance reports

---

Expand Down Expand Up @@ -1399,6 +1403,8 @@ The server starts at `http://localhost:9100` with the MCP endpoint at `/mcp`.

### 3.14 OBP-Sentinel

OBP-Sentinel, or Senti for short, is sold as **OBP Senti**, and as **TESOBE Senti** for systems that do not use OBP. See https://senti.tesobe.com.

**Purpose:** Watches running OBP-API instances, and the apps around them (API Explorer II, API Manager, the Portal, OBP-OIDC), works out what is actually going wrong or getting slower, and suggests the few improvements that matter most.

**How it works:**
Expand All @@ -1421,6 +1427,33 @@ See the Glossary item OBP-Sentinel.

See the Glossary items OBP Bank Node, Connector and Adapter.

### 3.16 OBP Cohort

**Purpose:** Runs startup programmes for incubators, accelerators, banks, regulators and innovation hubs, from the call for applications to graduation, in English and Arabic.

**Key Features:**

- Public calls with application forms, saved drafts and eligibility checks
- Reviews against a weighted rubric, with conflicts of interest declared first, and a ranked shortlist
- Milestones, sessions, attendance and surveys for each startup, and stage gates before graduation
- A Platform App in the OBP-Frontend repository (`apps/cohort`), keeping its records in OBP-API as Dynamic Entities

See https://cohort.tesobe.com and the Glossary item OBP Cohort.

### 3.17 Conformator

**Purpose:** Lets a regulator test the open banking APIs of the banks, payment service providers and third-party providers it supervises against the agreed standard, review the results and issue conformance reports.

**Key Features:**

- Requirements, and the tests that check them, kept in versioned suites; a suite can come from a standard OBP implements or from an OpenAPI document
- Each participant has a space of its own and runs the suites against its own non-production systems
- Participants submit results with evidence; reviewers assess them, and a separate approver decides
- Approval issues a report signed with Ed25519, which anyone can check by its reference
- Two Platform Apps in the OBP-Frontend repository: the web app (`apps/conformator`) and the runner that carries out the tests (`apps/conformator-runner`)

See the Glossary item Conformator.

---

## 4. Standards Compliance
Expand Down Expand Up @@ -2739,7 +2772,7 @@ GET /obp/v5.1.0/management/consumers

**Grant types:** a Consumer's grant types control how tokens can be obtained through it: whether people can log in through it, whether the application can get a token for itself (`client_credentials`), or both. A Consumer with no grant types set can be used in every way. Grant types do not decide what the application may do with a token.

**Platform Apps:** a Platform App is an application the installation runs as part of its own deployment, such as the Portal, API Manager, Opey, Sentinel, Cohort or a Bank Node. Only a Platform App can act as itself on its Consumer's Scopes (see 8.7).
**Platform Apps:** a Platform App is an application the installation runs as part of its own deployment, such as the Portal, API Manager, Opey, Sentinel, Cohort, Conformator or a Bank Node. Only a Platform App can act as itself on its Consumer's Scopes (see 8.7).

1. An administrator marks the Consumer as a Platform App (Role CanCreatePlatformApp).
2. The app declares the Scopes it needs, and what each one is for, every time it starts.
Expand Down
5 changes: 4 additions & 1 deletion obp-api/src/main/scala/code/api/DirectLoginRoutes.scala
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,10 @@ object DirectLoginRoutes {
triple <- DirectLogin.validatorFutureWithParams("authorizationToken", "POST", params)
(httpCode, message, dlParams) = triple
tokenTriple = DirectLogin.createTokenCommonPart(httpCode, message, dlParams)
_ <- Future(DirectLogin.grantEntitlementsToUseDynamicEndpointsInSpacesInDirectLogin(tokenTriple._3))
// The post-login grant runs only when a token was issued. On a refused login the third value is a state code
// (0, locked, email not validated, rate limited), not a user id, so the grant would find no user and log an ERROR.
_ <- if (tokenTriple._1 == 200) Future(DirectLogin.grantEntitlementsToUseDynamicEndpointsInSpacesInDirectLogin(tokenTriple._3))
else Future.unit
} yield {
if (tokenTriple._1 == 200) JSONFactory600.createTokenJSON(tokenTriple._2)
else code.api.util.APIUtil.unboxFullOrFail(Empty, None, tokenTriple._2, tokenTriple._1)
Expand Down
77 changes: 68 additions & 9 deletions obp-api/src/main/scala/code/api/util/Glossary.scala
Original file line number Diff line number Diff line change
Expand Up @@ -7334,9 +7334,11 @@ object Glossary extends MdcLoggable {
s"""
|# OBP-Sentinel
|
|**OBP-Sentinel** watches running OBP-API instances, and the apps around them (API Explorer II, the API Manager, the Portal, OBP-OIDC), for hours. It works out what is actually going wrong or getting slower, and suggests the few improvements that matter most. Fewer, better suggestions is the point.
|**OBP-Sentinel**, or Senti for short, watches running OBP-API instances, and the apps around them (API Explorer II, the API Manager, the Portal, OBP-OIDC), for hours. It works out what is actually going wrong or getting slower, and suggests the few improvements that matter most. Fewer, better suggestions is the point.
|
|Watching is plain code and costs nothing. Only the analyst, the source review and the questions a person asks on a finding (Trace history, Look again) use Claude, each with a spending limit.
|It is sold as OBP Senti, and as TESOBE Senti for systems that do not use OBP. See https://senti.tesobe.com.
|
|Watching is plain code and costs nothing. Only three things use Claude: the analyst, the source review, and the questions a person asks on a finding (Trace history, Look again). Each has a spending limit.
|
|## 1. Watching
|
Expand Down Expand Up @@ -7364,13 +7366,13 @@ object Glossary extends MdcLoggable {
|
|LEVEL is a log level (error, warning, info, debug, trace) or `all`. Each app lists these endpoints on its `/status` page.
|
|They are guarded by the same Roles as OBP-API's own endpoints: CanGetSystemLogCacheError, CanGetSystemLogCacheWarning and so on, one per level (`all` needs CanGetSystemLogCacheAll) and CanGetTelemetry. The app does not decide this itself: it passes the caller's token to OBP-API (GET /obp/v7.0.0/banks/SYS/my/roles/ROLE) and answers only if OBP-API says the Role is held. A call with no token gets 401, and a call without the Role gets 403.
|They are guarded by the same Roles as OBP-API's own endpoints: CanGetSystemLogCacheError, CanGetSystemLogCacheWarning and so on, one per level (`all` needs CanGetSystemLogCacheAll) and CanGetTelemetry. The app does not decide this itself. It passes the caller's token to OBP-API (GET /obp/v7.0.0/banks/SYS/my/roles/ROLE), and answers only if OBP-API says the Role is held. A call with no token gets 401, and a call without the Role gets 403.
|
|Sentinel finds the apps in OBP-API's app directory (GET /obp/v6.0.0/app-directory: public_obp_api_explorer_url, public_obp_api_manager_url, public_obp_portal_url, public_obp_oidc_url) and watches each like a small instance of its own, with its own findings, using its OBP-API instance's token. The analyst then reads the app's own source. An app has no aggregate metrics and no source review.
|Sentinel finds the apps in OBP-API's app directory (GET /obp/v6.0.0/app-directory: public_obp_api_explorer_url, public_obp_api_manager_url, public_obp_portal_url, public_obp_oidc_url). It watches each like a small instance of its own, with its own findings, using its OBP-API instance's token. The analyst then reads the app's own source. An app has no aggregate metrics and no source review.
|
|## 2. The analyst
|
|Every few hours, once Sentinel has watched for long enough, Claude reads a summary of what was collected (the last hours compared with the hours before) and reads the source code to find the cause of what stands out. Each problem it is confident about becomes a **finding**, scored by:
|Once Sentinel has watched for long enough, Claude reads a summary every few hours. It compares the last hours with the hours before. It then reads the source code to find the cause of what stands out. Each problem it is confident about becomes a **finding**, scored by:
|
|- **Impact**: how much it hurts users or the service;
|- **Confidence**: how sure the analyst is about the cause;
Expand All @@ -7380,11 +7382,18 @@ object Glossary extends MdcLoggable {
|
|## 3. Source review
|
|Besides following the logs, Sentinel can read the code of the endpoints each instance serves, looking for security problems such as SQL injection or missing authorisation checks. Go and Stop turn it on and off. It starts with the endpoints anyone can call without a login, then those that need a login, then those whose Role someone holds. It remembers what it read: an endpoint is read again only when its code changes.
|Sentinel can also read the code of the endpoints each instance serves. It looks for security problems such as SQL injection or missing authorisation checks. Go and Stop turn it on and off. It starts with the endpoints anyone can call without a login, then those that need a login, then those whose Role someone holds. It remembers what it read: an endpoint is read again only when its code changes.
|
|## 4. Suggestions
|
|A finding is suggested only if Sentinel has watched for long enough (4 hours by default), its priority is high enough, it was seen in more than one 15-minute period, and it was not already suggested, acted on, dismissed or fixed. At most 3 suggestions are made at a time, and at most 10 a week. When nothing qualifies, Sentinel says so rather than inventing work.
|A finding is suggested only when all of these are true:
|
|- Sentinel has watched for long enough (4 hours by default).
|- Its priority is high enough.
|- It was seen in more than one 15-minute period.
|- It was not already suggested, acted on, dismissed or fixed.
|
|At most 3 suggestions are made at a time, and at most 10 a week. When nothing qualifies, Sentinel says so rather than inventing work.
|
|## Using the page
|
Expand All @@ -7393,7 +7402,7 @@ object Glossary extends MdcLoggable {
|Each finding shows its evidence, why it happens, where in the code, and the suggested change. The copy button next to its title copies it all as text, ready to give to a coding agent.
|
|- **Trace history** lists the commits that changed the lines the finding names, and Claude says which commit introduced the problem (at most $$0.30).
|- **Look again: still an issue?** has Claude read the code the instance runs now, the commits since the finding was made, and whether its log messages are still seen. It answers in one line: still an issue, fixed (and by which commit), or could not tell. It takes a few minutes and costs at most $$0.50. While it works, the page shows how long it has been going and the command it is running. It does not change the finding's status.
|- **Look again: still an issue?** has Claude read the code the instance runs now and the commits since the finding was made. It also checks whether the finding's log messages are still seen. It answers in one line: still an issue, fixed (and by which commit), or could not tell. It takes a few minutes and costs at most $$0.50. While it works, the page shows how long it has been going and the command it is running. It does not change the finding's status.
|- **Look again at the security findings to review**, above the list, does the same for each security finding in To review, one at a time. Those Claude finds fixed are marked fixed and move to Done, with Claude's answer as the comment.
|
|Then answer, with a comment for the analyst if you like:
Expand All @@ -7408,7 +7417,11 @@ object Glossary extends MdcLoggable {
|
|## The Secured check
|
|Once an hour Sentinel calls the endpoints it reads (log cache, Telemetry and, for OBP-API, aggregate metrics) without a token. They must refuse. The header shows **Secured** when every one refused (401 or 403), **Open** when at least one answered with data (fix this first: anyone can read those logs), and **Could not tell** when some gave no answer or an unexpected one, such as 404.
|Once an hour Sentinel calls the endpoints it reads (log cache, Telemetry and, for OBP-API, aggregate metrics) without a token. They must refuse. The header shows one of these:
|
|- **Secured:** every one refused (401 or 403).
|- **Open:** at least one answered with data. Fix this first, because anyone can read those logs.
|- **Could not tell:** some gave no answer, or an unexpected one such as 404.
|
|## What Sentinel needs
|
Expand All @@ -7423,6 +7436,52 @@ object Glossary extends MdcLoggable {
|""".stripMargin)


glossaryItems += GlossaryItem(
title = "OBP Cohort",
description =
s"""
|# OBP Cohort
|
|**OBP Cohort** runs startup programmes for incubators, accelerators, banks, regulators and innovation hubs, from the call for applications to graduation, in English and Arabic.
|
|- **Call:** a call is published on a public site, and anyone can apply.
|- **Apply:** forms with attachments, saved drafts, and eligibility checked when the form is sent.
|- **Evaluate:** reviewers declare any conflict of interest, then score each application against the call's weighted rubric. Staff see a ranked shortlist and record each decision.
|- **Deliver:** milestones, sessions, attendance, surveys and discussions for each startup.
|- **Graduate:** stage gates are checked before a startup moves on, and it gets a certificate.
|
|## How it uses OBP-API
|
|OBP-API is Cohort's only backend. Its records are Dynamic Entities in a space of its own, and it uses OBP's Users, login, Roles, Customers, Files and messages. Cohort is a Platform App: it declares the Scopes it needs, and an administrator grants them.
|
|It is part of the OBP-Frontend repository (`apps/cohort`). See https://cohort.tesobe.com.
|""".stripMargin)


glossaryItems += GlossaryItem(
title = "Conformator",
description =
s"""
|# Conformator
|
|**Conformator** lets a regulator test the open banking APIs of the banks, payment service providers and third-party providers it supervises against the agreed standard. The regulator reviews the results and issues conformance reports.
|
|The name is the Latin *conformator*, "one who shapes": the regulator sets the shape, and Conformator checks each participant's API against it.
|
|## From the rules to a signed report
|
|1. **Define:** the rules are recorded as requirements, and the tests that check each one are grouped into versioned suites. A suite's endpoints come from a standard OBP implements, or from an OpenAPI document.
|2. **Admit:** each participant is registered and given a space of its own, kept apart from everyone else's.
|3. **Test:** participants run the suites against their own non-production systems, as often as they need.
|4. **Review:** participants submit their results with evidence. Reviewers assess them, and an approver who did not assess makes the decision. Participants can ask for waivers and appeal.
|5. **Report:** approval issues a report signed with Ed25519. Anyone can check a report by its reference, without trusting the site that shows it.
|
|## How it uses OBP-API
|
|Conformator is two Platform Apps in the OBP-Frontend repository: the web app (`apps/conformator`) and the runner (`apps/conformator-runner`). The runner carries out the tests and records each result. Both keep their records in OBP-API as Dynamic Entities, in a central space and in each participant's space, and each declares the Scopes it needs.
|""".stripMargin)


glossaryItems += GlossaryItem(
title = "OAuth Standards and OBP",
description =
Expand Down
3 changes: 2 additions & 1 deletion obp-api/src/main/scala/code/api/v1_2_1/Http4s121.scala
Original file line number Diff line number Diff line change
Expand Up @@ -967,7 +967,8 @@ object Http4s121 {
|${userAuthenticationMessage(true)} and the user needs to have access to the owner view.""",
EmptyBody,
EmptyBody,
List(AuthenticatedUserIsRequired, BankAccountNotFound, CannotRevokeOwnAccountAccess, UnknownError, "user does not have access to owner view on account"),
// UserLacksPermissionCanRevokeAccessToViewForTargetAccount: the caller cannot revoke one of the views the target user holds
List(AuthenticatedUserIsRequired, BankAccountNotFound, CannotRevokeOwnAccountAccess, UserLacksPermissionCanRevokeAccessToViewForTargetAccount, UnknownError, "user does not have access to owner view on account"),
List(apiTagView, apiTagAccount, apiTagUser, apiTagOwnerRequired),
http4sPartialFunction = Some(removePermissionForUserForBankAccountForAllViews)
)
Expand Down
8 changes: 7 additions & 1 deletion obp-api/src/main/scala/code/api/v2_2_0/Http4s220.scala
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,8 @@ object Http4s220 {
| You should use a leading _ (underscore) for the view name because other view names may become reserved by OBP internally
| """,
createViewJsonV121, viewJSONV220,
List(AuthenticatedUserIsRequired, InvalidJsonFormat, BankAccountNotFound, UnknownError),
// SourceViewHasLessPermission: the body asks for actions none of the caller's views on the account has
List(AuthenticatedUserIsRequired, InvalidJsonFormat, BankAccountNotFound, SourceViewHasLessPermission, UnknownError),
List(apiTagAccount, apiTagView, apiTagOldStyle), None,
http4sPartialFunction = Some(createViewForBankAccount))

Expand All @@ -212,6 +213,11 @@ object Http4s220 {
_ <- code.util.Helper.booleanToFuture(
s"${CreateCustomViewError} You need the `${CAN_CREATE_CUSTOM_VIEW}` permission on any your views",
cc = Some(cc)) { anyCanCreate }
// the new view may only get actions the caller already has on one of their views of this account, else they create a view with more and grant it to themselves (as Update View and v5.1.0 check)
callerActions = permission.views.flatMap(_.allowed_actions).toSet
_ <- code.util.Helper.booleanToFuture(
s"$SourceViewHasLessPermission Current permissions of your views ($callerActions), target view permissions (${createBodyJson.allowed_actions})",
failCode = 403, cc = Some(cc)) { createBodyJson.allowed_actions.toSet.subsetOf(callerActions) }
createViewJson = CreateViewJson(
createBodyJson.name,
createBodyJson.description,
Expand Down
Loading
Loading