# WMIS

Wealth Management Intelligence System is a TypeScript service that exposes a small MCP-style tool runtime, OAuth 2.1 PKCE token flow, and SPIFFE/SPIRE identity primitives for wealth management workloads.

WMIS is currently an API foundation and documentation artifact for enterprise wealth-management workflows. It is not proof of production deployment, regulatory certification, or a complete advisor workstation.

## Documentation

- [Compliance Architecture Plan](docs/COMPLIANCE-ARCHITECTURE-PLAN.md)
- [Product Plan](docs/PRODUCT.md)
- [Agent Instructions](docs/AGENTS.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
- [API Reference](docs/API.md)
- [Security Guide](docs/SECURITY.md)

## Architecture

The service starts an Express API in `src/index.ts`, wires the MCP server from `src/mcp-server.ts`, and initializes the identity layer in `src/spiffe-spire.ts`.

- MCP tools are registered in memory and invoked through authenticated REST routes.
- OAuth uses authorization-code plus PKCE (`S256`) and rotates refresh tokens on use.
- Access tokens are JWTs signed by the service and validated by Express middleware.
- Rate limiting is tracked per authenticated client, `x-client-id`, or source IP.
- SPIFFE identity prefers a configured Workload API endpoint and falls back to locally issued JWT-SVIDs and rotating key material for development.
- Logs are structured JSON lines with request IDs and operational event names.

The current process keeps OAuth authorization code state, refresh token state, rate-limit buckets, and MCP tool registration in memory. Production use should replace or wrap those areas with durable enterprise controls where required.

## Product Scope

WMIS is intended for AI-assisted wealth-management workflows such as portfolio risk review, suitability pre-checks, advisor preparation, compliance triage, and auditable MCP tool execution. The initial pilot described in the docs targets Henssler Financial and should use approved pilot data, human review, and explicit compliance boundaries.

The product roadmap includes governed Open Knowledge Format artifacts, persistent audit storage, role and scope controls, enterprise IdP integration, SPIRE deployment, and commercialization packaging for additional wealth-management firms.

## Setup

```bash
npm install
npm run typecheck
npm run dev
```

Build and run:

```bash
npm run build
npm start
```

`npm run dev` starts the TypeScript service directly with `ts-node`. `npm run build` emits JavaScript into `dist`, and `npm start` runs `dist/index.js`.

There is currently no `npm test` script.

## Environment

- `PORT`: HTTP port, default `3001`.
- `JWT_SECRET`: HMAC secret for OAuth access tokens. Set this in every non-development environment.
- `OAUTH_ISSUER`: JWT issuer, default `https://wmis.local`.
- `OAUTH_AUDIENCE`: JWT audience, default `wmis-api`.
- `RATE_LIMIT_MAX`: requests per rate-limit window, default `120`.
- `RATE_LIMIT_WINDOW_MS`: rate-limit window in milliseconds, default `60000`.
- `SPIFFE_TRUST_DOMAIN`: SPIFFE trust domain, default `wmis.local`.
- `SPIFFE_ID`: workload SPIFFE ID, default `spiffe://wmis.local/workload/wmis-api`.
- `SPIRE_WORKLOAD_API_ENDPOINT`: optional HTTP endpoint for a SPIRE-compatible Workload API bridge.
- `SVID_TTL_SECONDS`: local JWT-SVID TTL, default `3600`.

Do not commit production secrets or real client data. The default `JWT_SECRET` is development-only.

## API Reference

Default local base URL: `http://127.0.0.1:3001`.

### `GET /health`

Liveness probe. Does not require authentication.

### `POST /api/oauth/authorize`

Starts an OAuth 2.1 PKCE flow and returns an authorization code.

```json
{
  "clientId": "advisor-console",
  "redirectUri": "https://client.example/callback",
  "codeChallenge": "base64url-sha256-code-verifier",
  "codeChallengeMethod": "S256",
  "scope": "mcp:tools",
  "state": "opaque-client-state",
  "subject": "advisor-123"
}
```

### `POST /api/oauth/token`

Exchanges an authorization code for an access token:

```json
{
  "grantType": "authorization_code",
  "code": "returned-code",
  "codeVerifier": "original-code-verifier",
  "clientId": "advisor-console",
  "redirectUri": "https://client.example/callback"
}
```

Refreshes access with a refresh token:

```json
{
  "grantType": "refresh_token",
  "refreshToken": "returned-refresh-token",
  "clientId": "advisor-console"
}
```

### `GET /api/tools`

Lists registered MCP tools. Requires `Authorization: Bearer <accessToken>`.

### `POST /api/tools/:name/call`

Invokes a registered MCP tool. Requires `Authorization: Bearer <accessToken>`.

```json
{
  "input": {
    "positions": [
      { "symbol": "AAPL", "marketValue": 100000, "riskScore": 62 }
    ]
  }
}
```

### `GET /api/identity/svid`

Returns the current SVID and trust bundle. Requires `Authorization: Bearer <accessToken>`.

See [docs/API.md](docs/API.md) for request and response samples, error shapes, MCP notes, and authentication assumptions.

## Built-in Tools

- `portfolio_risk_summary`: computes total market value, weighted risk score, largest position, and position count.
- `compliance_suitability_check`: evaluates proposed allocations against risk tolerance and liquidity constraints.

## Deployment

The expected service port is `3001` unless `PORT` is set. A typical VPS deployment builds the service, starts `dist/index.js` with PM2, and places a TLS-terminating reverse proxy in front of it.

```bash
npm install
npm run typecheck
npm run build
JWT_SECRET="$WMIS_JWT_SECRET" PORT=3001 pm2 start dist/index.js --name wmis
curl -sS http://127.0.0.1:3001/health
```

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for PM2, rollback, environment, and operations checks.

## Security and Compliance

WMIS includes security primitives, but production compliance depends on deployment architecture, firm policy, operational evidence, retention controls, and supervisory review.

Important current boundaries:

- OAuth client registration, redirect allowlists, durable token storage, and route-level scope enforcement are not complete in this repository.
- SPIFFE/SPIRE can be integrated through `SPIRE_WORKLOAD_API_ENDPOINT`; local SVID issuance is a development fallback.
- Logs are structured, but durable audit storage and retention controls must be added for production compliance use.
- AI or MCP outputs should not be treated as final client advice or regulatory approval without human review and firm-approved policy.

See [docs/SECURITY.md](docs/SECURITY.md) and [docs/COMPLIANCE-ARCHITECTURE-PLAN.md](docs/COMPLIANCE-ARCHITECTURE-PLAN.md).