Banking Demo

银行演示——PingOne版

⚠️ 免责声明： 这是一个独立的社区演示项目。它是 不 由PingOne或ForgeRock创建、背书或支持。使用风险自负。不提供任何明示或暗示的保证。

使用PingOne进行身份验证和验证的独立AI银行演示 RFC 8693令牌交换 因此AI代理可以代表用户安全地访问银行数据。

这是一个 完全独立 项目——它可以交给任何人并独立运行。

人工智能助理/代理： 跟随 CLAUDE.md （回购约定、回归保护、验证）。

组件

新机器设置

TL；DR——单线安装

如果你有 节点20+ （节点20、22或24——任何现代LTS都可以工作）和 版本控制系统 现在，这就是你所需要的：

curl -fsSL https://raw.githubusercontent.com/curtismu7/banking-demo/main/install.sh | bash

安装程序：

1. 确认安装目录（默认为 ./banking-demo 在您当前的目录中；您可以按Enter或中止）。
2. 克隆仓库（如果已经存在，则提取最新版本）。
3. 跑 npm run setup:fresh 在它内部——它通过localhost浏览器表单提示输入PingOne worker creds，提供所有PingOne资源，并写入 banking_api_server/.env.

完成后： cd banking-demo && ./run-bank.sh就这样。

它将安装在哪里？

安装程序创建 banking-demo/ 在您当前的工作目录中。在运行卷曲线之前，请选择您想要的位置：

# Suggested: install under your home directory
cd ~
curl -fsSL https://raw.githubusercontent.com/curtismu7/banking-demo/main/install.sh | bash
# → /Users/you/banking-demo/

# Or somewhere temporary
cd /tmp
curl -fsSL https://raw.githubusercontent.com/curtismu7/banking-demo/main/install.sh | bash
# → /tmp/banking-demo/

安装程序打印绝对目标路径 之前 做任何事，问 Proceed? [Y/n].按 n 如果路径错误，则中止，然后从其他路径重新运行 cwd.

覆盖安装路径

curl -fsSL https://raw.githubusercontent.com/curtismu7/banking-demo/main/install.sh | INSTALL_DIR=~/work/banking-demo bash

其他环境变量覆盖（主要用于测试/CI）：

从另一台计算机迁移

将tar存档作为参数传递：

curl -fsSL https://raw.githubusercontent.com/curtismu7/banking-demo/main/install.sh | bash -s -- /path/to/banking-export-.tar.gz

bash -s -- 是通过curl管道转发参数的标准模式。安装程序链导入→ 自动引导；如果存档比 MCP_GW / AGENT 应用程序被添加，bootstrap填补了空白。

重新运行安装程序

安全。如果 banking-demo/ 已存在git checkout，安装程序会执行 git pull --ff-only 而不是 git clone，然后重新运行setup:fresh。PingOne配置是幂等的——检测并重用已有的资源；如果现有应用程序上的重定向URI不匹配，则会刷新它们。

如果你已经克隆了仓库

直接运行内部命令——同样的流程，跳过克隆：

cd banking-demo
npm run setup:fresh                              # brand-new install
npm run setup:fresh -- /path/to/archive.tar.gz   # migration

两个流都在同一个地方结束：一个工作流 .env，还原数据（如果您导入了数据），配置PingOne资源，准备就绪 ./run-bank.sh。以下部分将介绍先决条件和完整顺序。

默认值和预设值——每个命令的作用

两者 npm run setup:fresh 和 npm run import 在每次交互运行开始时打印此表，然后询问“继续使用这些默认值吗？\[Y/n\]”，这样您就可以在开始任何配置之前退出并选择不同的配方。

npm run setup:fresh 默认值

Helix env变量（如果所有五个变量都已设置，则在非交互模式下自动配置）： HELIX_BASE_URL, HELIX_API_KEY, HELIX_ENVIRONMENT_ID, HELIX_AGENT_ID, HELIX_PROMPT_FIELD_ID.

npm run import 默认值

预设--复制和粘贴

# 1) Fresh install on this machine (the default)
npm run setup:fresh

# 2) Migrate from another machine using a bundle
npm run setup:fresh -- ~/banking-export-2026-XX-XX.tar.gz

# 3) Nuclear reset (wipe local state AND PingOne env, then re-provision)
npm run reset

# 4) CI / scripted (no prompts; needs PINGONE_BOOTSTRAP_* + HELIX_* env vars)
npm run setup:fresh -- --non-interactive --skip-helix

# 5) Just import a bundle (no PingOne work, no Helix)
npm run import -- ~/banking-export-2026-XX-XX.tar.gz

# 6) Just check this machine can import (no side effects)
npm run import -- --preflight-only ~/banking-export-2026-XX-XX.tar.gz

工作示例——完全擦除并从空白开始

当某物漂移时(.env 出现故障，PingOne应用程序与本地状态不匹配，您正在对已配置的租户测试新的安装路径）最干净的重置是一个命令：

cd banking-demo
npm run reset

这是端到端运行的（它是 setup:fresh --clean --reset-pingone 引擎盖下）：

完成后：

./run-bank.sh                      # start everything against the new state
./run-bank.sh status               # verify all 8 services are healthy

如果你想在最后一步导入一个已知良好的捆绑包，而不是让引导程序重新配置，请使用 npm run reset:import -- /path/to/bundle.tar.gz （相同的擦拭+顶部的捆绑）。

卸载--删除所有内容

当你在这台机器上完成演示并想释放磁盘/让PingOne租户保持干净时：

cd banking-demo
npm run uninstall

它的作用（4个阶段——每个阶段都可以通过以下方式跳过 --keep-* 旗帜）：

跳过各个阶段：

npm run uninstall -- --keep-pingone        # local cleanup only
npm run uninstall -- --keep-node-modules   # don't free the 2 GB of deps
npm run uninstall -- --keep-services       # services are already down
npm run uninstall -- --keep-local          # only stop services + wipe PingOne

什么 uninstall 做 非 删除（手动执行这些操作）：

• repo目录本身-- rm -rf banking-demo 脚本运行后
• 源代码（全部在git树中；未删除）
• 你的shell的nvm引导程序(~/.zshrc / ~/.bashrc 线路）
• mkcert 根CA（计算机范围；影响其他应用程序）
• 你的Helix租户中的任何内容——脚本都不会触及Helix

跑 npm run uninstall -- --help 查看完整的旗帜列表。

其他npm快捷方式

# Day-to-day
npm run pingone:bootstrap          # re-provision PingOne (idempotent; reuses existing apps)
npm run import -- archive.tar.gz   # restore .env + data from a tar (no PingOne work)
npm run export                     # create a banking-export-.tar.gz

# Destructive (require confirmation prompts)
npm run pingone:recreate           # delete 'Super Banking *' apps and recreate
npm run pingone:wipe               # NUCLEAR: delete every app/resource/group/user in the PingOne env
npm run reset                      # full wipe + start blank: local state + PingOne + re-provision
npm run reset:import -- archive.tar.gz
                                   # full wipe + import (wipe → import → bootstrap)
npm run uninstall                  # full tear-down: stop services + wipe PingOne + delete local + node_modules

reset 和 pingone:wipe 两者都要求您在销毁任何东西之前键入环境id进行确认。

______________________________________________________________________

路径A——新安装（首次在此计算机上）

先决条件： 节点 20或更新 （节点20、22、24——任何现代LTS；用 node --version)npm 9+，Git， 证书制作工具

注意——Node 20+必须在您运行命令的shell中处于活动状态。 如果通过nvm安装Node（推荐），nvm是一个shell函数——打开一个不会自动加载的新终端 zsh: command not found: nvm.确保你的 ~/.zshrc （或 ~/.bashrc)来源nvm；看见 下文第0节.

0.节点版本设置（如果 node --version 显示 v20.… 或更新）

# Install nvm if you don't have it yet:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Make nvm load in EVERY new terminal — append to ~/.zshrc (zsh) or ~/.bashrc (bash):
cat >> ~/.zshrc  `banking_api_ui` 船舶A `.npmrc` 随着 `legacy-peer-deps=true` 太简单了 `npm install` 也可以在那里工作——上面的明确标志是安全带和吊带，如果 `.npmrc` 永远迷失。CRA/`react-scripts` 有一个无法解决的问题 `peerOptional` 对于npm 7+默认拒绝的TypeScript。

#### 3.启动所有服务

> 逃离 `banking-demo` 回购根。 `./run-bank.sh` 回购是本地的-- `cd banking-demo` 首先，如果你打开了一个新的终端。

cd /path/to/banking-demo # if you're not already there ./run-bank.sh

`run-bank.sh` 将：

- 来源 `~/.nvm/nvm.sh` 和 `nvm use 20` 如果nvm尚未加载到当前shell中（因此它可以在不自动加载nvm的新终端上工作）
- 如果安装了mkcert，则自动生成TLS证书
- 创建一个 `.env` a生成 `SESSION_SECRET` 首次启动时
- 启动API（3001）、UI（4000）、MCP（8080）和LangChain代理（8888）

> 如果根本没有安装nvm，脚本将返回到与§0相同的指导，并带指令退出。

#### 4.提供PingOne（推荐）-- `npm run setup:fresh`

这个命令可以创建PingOne所需的一切（资源服务器、作用域、应用程序、带密码的演示用户），并将凭据写入 `banking_api_server/.env`。它为您的worker creds弹出一个localhost表单，这样您就不会将机密粘贴到终端中。

**步骤1（您在PingOne管理控制台中）：** 使用创建worker应用程序 **身份数据管理员** 角色。注意环境ID、区域、客户端ID和客户端密码。

**步骤2（在这个仓库中，从根开始）：**

npm run setup:fresh

浏览器弹出一个表单。提交你的四个工人证书。脚本：

1. 配置资源服务器(`Super Banking API`, `Super Banking MCP Server`, `Super Banking MCP Gateway`)
1. 创建约25个作用域(`banking:*`, `admin:*`, `users:*`, `p1:*`, `banking:mcp:invoke`)
1. 创造 **7应用程序** （管理员、用户、MCP服务器、工作人员、MCP交换机、MCP网关、代理）
1. 使用生成的密码创建两个演示用户(`bankuser`, `bankadmin`)
1. 添加 `bankingPrincipalUserId` 模式属性和SPEL/may_act令牌声明
1. 写 `banking_api_server/.env` 使用所有新的客户端ID和机密（保留您的 `SESSION_SECRET` 所以 `config.db` 保持可解密）

剧本是 **幂等** --在完全配置的环境中重新运行它会为每个资源报告“存在”并干净地退出。

**其他模式：**

- `npm run setup:fresh -- --no-browser` --仅终端提示（SSH/无头盒）
- `cd banking_api_server && npm run pingone:bootstrap:ci` 随着 `PINGONE_BOOTSTRAP_*` env变量集--非交互式（CI/CD自动化）

**更喜欢手动输入凭据吗？** 打开 **[https://api.ping.demo:4000/configure](https://api.ping.demo:4000/configure)** 在浏览器中 `./run-bank.sh` 并输入您的PingOne环境ID和OAuth客户端凭据。应用程序将它们保存到 `config.db` --无需重新启动。注意：此手动路径仅设置管理员/用户OAuth客户端。MCP网关和代理服务仍然需要 `MCP_GW_CLIENT_ID` / `AGENT_CLIENT_ID` 在 `.env`，其中 `setup:fresh` 自动提供。

看 **[docs/SETUP.md](docs/SETUP.md)** 获取完整的PingOne应用程序配置参考。

______________________________________________________________________

### 路径B--从另一台计算机迁移

如果您已经在机器a上进行了工作设置，并希望将其带到机器B上，而您的所有PingOne配置、数据和环境都完好无损。

#### A机出口

cd banking_api_server npm run data:export

Creates banking-export-.tar.gz in banking_api_server/

档案包括 `config.db`, `banking.db`，所有数据文件，以及 `.env`.\
它不包括 `sessions.db` （机器绑定）和 `certs/` （必须重新生成）。

> **安全：** 存档包含您的 `.env` 以及数据库机密。通过传输 `scp` 或加密USB——不要提交git或上传到公共存储。

#### 在机器B上——设置机器，然后运行setup:fresh with tar

1. Node 20+ in this shell (see Path A § 0 if nvm isn't loaded yet)

nvm use 20 # or: source ~/.zshrc && nvm use 20 (or use 22 / 24 — any LTS)

2. One-time machine prep (same as Path A § 1)

brew install mkcert && mkcert -install echo '127.0.0.1 api.ping.demo' | sudo tee -a /etc/hosts

3. Clone (run-bank.sh installs all deps for you on first start)

git clone https://github.com/curtismu7/banking-demo.git cd banking-demo

4. Copy the archive from Machine A, then import + provision in one step

npm run setup:fresh -- /path/to/banking-export-.tar.gz

5. Generate TLS certs (machine-bound — not in the archive)

mkdir -p certs && cd certs && mkcert api.ping.demo localhost 127.0.0.1 && cd ..

6. Start

./run-bank.sh

> 步骤4链条 `data:import` 然后 `pingone:bootstrap`。如果您的存档已经具有完整的PingOne配置（最近导出的 `MCP_GW_CLIENT_ID` / `AGENT_CLIENT_ID`)，自动跳过引导步骤，命令在“导入完成”时退出。如果存档较旧或PingOne配置缺失，浏览器会弹出worker cred表单，这样您就可以一次性完成配置。

> 导出、导入和引导脚本都是将Node版本与仓库进行预飞行 `engines.node` 如果你选错了专业，可以带一条明确的信息退出——所以如果步骤4以“需要节点专业20”结束，这就是在重试之前修复步骤1的提示。

什么是进口部分 `setup:fresh` 做：

- 备份现有 `data/persistent/` 在写任何东西之前
- 恢复所有数据文件和 `.env`
- 运行配置健康检查，如果出现任何故障，则显示回滚命令
- 需要时，放手引导；否则打印“导入完成”并退出

#### 验证导入是否成功

打开 **[https://api.ping.demo:4000/configure](https://api.ping.demo:4000/configure)** --它应该显示“导入已验证”，并加载了您的PingOne凭据。

______________________________________________________________________

### 新机器设置故障排除

|症状|可能原因|修复|
|---|---|---|
| `zsh: command not found: nvm` |nvm没有加载到这个shell中——它是一个shell函数，而不是PATH上的二进制文件| `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"` （一个镜头），然后将这两行添加到 `~/.zshrc` （或 `~/.bashrc`)所以新的终端会自动接收它。见路径A§0。 |
| `zsh: no such file or directory: ./run-bank.sh` |您不在repo根目录中-- `./run-bank.sh` 回购是本地的| `cd /path/to/banking-demo` 首先，然后 `./run-bank.sh` |
|导出/导入失败 `Node major 20 required, but this shell is using Node vX` |此shell中活动的节点版本错误| `nvm use 20` （如果需要，请先运行上面的nvm加载片段）；见路径A§0|
|浏览器显示证书错误|证书未生成或CA不受信任|运行 `mkcert -install` 然后 `cd certs && mkcert api.ping.demo localhost 127.0.0.1` |
| `api.ping.demo` 无法解决| `/etc/hosts` 条目缺失| `echo '127.0.0.1 api.ping.demo' \| sudo tee -a /etc/hosts` |
| `/configure` 导入后显示所有字段为空| `.env` 加密密钥不匹配|使用原始存档重新导入；确保 `.env` 包括源机器|
| `better-sqlite3` 启动时出现二进制错误|节点版本不匹配（针对不同节点主节点构建的二进制文件）| `nvm use 20 && cd banking_api_server && npm rebuild better-sqlite3` |
|导入失败，显示“服务器正在运行”|导入前必须停止服务器| `./run-bank.sh stop` 然后重试导入|
| `npm install` 在 `banking_api_ui` 失败与 `ERESOLVE` （打字/反应脚本）|CRA `peerOptional` typescript范围触发npm 7+解析器| `npm install --legacy-peer-deps` （或恢复 `banking_api_ui/.npmrc` 包含 `legacy-peer-deps=true`) |

______________________________________________________________________

## 这个演示程序做什么

看 **[docs/FEATURES.md](docs/FEATURES.md)** --演示场景、全功能矩阵、20分钟演讲清单。\
看 **[docs/RFC-STANDARDS.md](docs/RFC-STANDARDS.md)** --实施的每个RFC和标准、合规级别和已知差距。

## 配置

看 **[docs/SETUP.md](docs/SETUP.md)** （§2-PingOne应用程序配置和§3--环境变量）以获取完整的配置参考，包括所有必需的环境变量及其PingOne源代码。

Architecture

┌─────────────────────────────────────────────────────────┐
│              银行数字助理│
│                                                           │
│  banking_api_ui（：3000）←→banking_api_server（：3001）│
│       React UI Express银行API│
│                                    ↑ JWT验证│
│                                    │ 通过PingOne JWKS│
│                                                           │
│  langchain_agent（：8888）←→banking_mcp_server（：8080）│
│    LangChain+OpenAI MCP银行工具│
│           ↓ 代币交换│
│    oauth游乐场（：3001）（或直接PingOne）│
└─────────────────────────────────────────────────────────┘
↓
PingOne（auth.pyone.com）
环境：b9817c16-。..

Reference Architecture (i4ai Token Exchange Flow)

The diagram in i4ai-ref-arch.mmd illustrates the complete token exchange flow for delegated AI agent access in this banking demo:

1. Agent context (no user subject) — Agent requests tool list with its own credentials; authorization server returns tools matching agent's scopes
2. User context required — User authenticates via web app and requests access to banking data through the chatbot
3. Subject token (user → agent) — Chatbot requests a scoped token for the agent with may_act claim indicating agent can act on behalf of user
4. RFC 8693 Token Exchange — Agent exchanges user token + agent token for a delegated token scoped to MCP gateway, carrying both sub: user and act: agent1
5. Downstream delegation — Gateway exchanges for MCP-scoped token, MCP exchanges for resource-server-scoped token; each hop re-issues with same delegation chain
6. Authorization decisions — Ping Authorize validates token claims, scope, and tool policy at each hop; Resource Server validates final token before returning data

See README (mermaid).md.md) for detailed token operations, introspection patterns, delegation chain semantics, and standards references.

Key Changes from Original (ForgeRock/PingOne AI IAM Core → PingOne)

Services

Token Exchange Flow (RFC 8693)

The Backend-for-Frontend (BFF) — the banking_api_server — performs RFC 8693 Token Exchange on the server side — the browser never sees raw OAuth tokens. On every POST /api/mcp/tool call, agentMcpTokenService.js runs:

1. Retrieve the user access token (stored in server-side session)
2. POST {issuer}/as/token
     grant_type = urn:ietf:params:oauth:grant-type:token-exchange
     subject_token = 
     subject_token_type = urn:ietf:params:oauth:token-type:access_token
     audience =           -- binds audience to MCP server
     scope =                   -- e.g. banking:accounts:read
3. PingOne validates may_act, issues the MCP access token (delegated, MCP audience)
4. BFF opens WebSocket to banking_mcp_server with the MCP access token as Bearer

可选委派路径(USE_AGENT_ACTOR_FOR_MCP=true):

     actor_token =    -- client-credentials token
     actor_token_type = urn:ietf:params:oauth:token-type:access_token
     -- MCP access token carries act: { sub: "" }  per RFC 8693 s4.1

交易所 休眠，直到配置 --如果 MCP_RESOURCE_URI 如果未设置，BFF不会向MCP发送该路径的令牌（本地工具回退；用户访问令牌保留在BFF上）。要激活：

PingOne中需要：在前端后端（BFF）客户端上启用令牌交换授权类型，并配置 may_act /演员政策，所以PingOne将接受交换。

需要PingOne配置

在PingOne环境中(b9817c16-9910-4415-b67e-4ac687da74d9)，您需要：

1. 超级银行员工代币应用程序 （客户端凭据，类型： WORKER)-PingOne管理API访问

- 已配置： 66a4686b-9222-4ad2-91b6-03113711c9aa

1. 网络应用 （auth_code+PKCE）--用于用户登录

- 已配置： a4f963ea-0736-456a-be72-b1fa4f63f81f

1. 代币交换 前端后端（BFF）客户端的策略--允许前端后端（BF）将用户令牌交换为MCP受众令牌

- 在PingOne：应用程序→ 您的前端后端（BFF）应用程序→ 资助类型→ 启用 代币交换 - 添加令牌交换策略：主题令牌发行者=此PingOne环境；允许的受众=价值 MCP_RESOURCE_URI - 添加一个 may_act 声明向最终用户发放的令牌（属性映射），因此前端后端（BFF）的client_id出现在 may_act.client_id

MCP安全网关——潜在架构

注： 这不是应用程序当前的设置方式。它说明了如何 MCP安全网关 （如PingOne所定义）可以被引入，以集中身份执行 银行代理和银行MCP服务器——无需更改任何端点的代码。

flowchart LR
    subgraph Customer["🏦 Banking App Infrastructure"]
        direction TB
        GATEWAY["🔴 MCP Security Gateway\n(policy enforcement point)"]
        MCP_SERVER["Banking MCP Server\n:8080\ntools: balance · transfer · transactions"]
    end

    subgraph PingCloud["☁️ Ping"]
        PING["PingOne Platform\n(PingOne)\n• token validation\n• policy evaluation\n• step-up MFA decisions"]
    end

    BANKING_AGENT["🤖 Banking Agent\n(LangChain FAB)\n:8888"]

    BANKING_AGENT -- "1. MCP tool call\n(access_token in header)" --> GATEWAY
    GATEWAY -- "3. Forward validated\nrequest (adapted)" --> MCP_SERVER
    MCP_SERVER -- "tool result" --> GATEWAY
    GATEWAY -- "response" --> BANKING_AGENT
    GATEWAY  PING

    style GATEWAY fill:#c0392b,color:#fff,stroke:#922b21
    style PING fill:#e8a0a0,color:#333,stroke:#c0392b
    style BANKING_AGENT fill:#f0f0f0,stroke:#333
    style MCP_SERVER fill:#f0f0f0,stroke:#333

它将如何在实践中发挥作用：

这将为银行演示增加关键好处：

• 每个MCP工具调用的集中审计日志
• 在高风险工具（例如。 transfer_funds)
• 网关上的令牌交换——MCP服务器永远看不到用户的原始令牌
• 在不更改代理身份验证逻辑的情况下更换MCP服务器

______________________________________________________________________

Vercel部署

该应用程序作为单个无服务器功能部署到Vercel(api/handler.js)React UI作为静态文件。Vercel会启动多个函数实例，因此会话必须在外部持久化 升级Redis.

快速Vercel设置

运行交互式设置向导——它检测冲突，验证Uptash连接，生成会话密钥，并可选择通过CLI将值推送到Vercel：

npm run setup:vercel

要检查当前配置而不进行更改，请执行以下操作：

npm run setup:vercel:check

巫师写了一个 .env.vercel.local 文件（gitignored）。将这些值复制到 Vercel 仪表盘→ 项目→ 设置→ 环境变量.

所需的环境变量

重要提示： 不要设置 REDIS_URL 对一个 https:// URL--必须是 redis:// 或 rediss:// 有线协议，或使用 UPSTASH_REDIS_REST_URL 相反。安装向导会自动检测并修复此问题。

重要提示： 从不设置 SKIP_TOKEN_SIGNATURE_VALIDATION=true --服务器将拒绝在生产环境中启动。

会话商店：为什么要升级REST？

Vercel的无服务器环境会终止调用之间的TCP连接。 node-redis （有线协议）是不可靠的，因为每次冷启动都会导致TLS握手，从而占用会话读/写窗口。该应用程序使用 @vercel/kv （通过HTTP升级REST API）-设计为无状态，无需重新建立连接。

部署后验证

部署后，注销并重新登录，然后检查：

GET /api/auth/debug

你想要：

• sessionStoreType: "upstash-rest"
• sessionStoreHealthy: true
• sessionRestored: false （在新登录后——而不仅仅是cookie回退）

Pingone重定向URI

在获取Vercel URL后，将这些添加到PingOne应用程序中：

• 管理员： https:///api/auth/oauth/callback
• 客户： https:///api/auth/oauth/user/callback

Vercel常见问题

______________________________________________________________________

环境文件