Skip to content
Closed
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
114 changes: 114 additions & 0 deletions suggestions/website/external-ip-kpi-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
title: External IP Tile Contract
description: Constructional contract to remove the landing External IP tile, because GET /status has no external_ip or ip field and a public lookup would fight the LAN-only design.
last_updated: 2026-10-05
owner: maintainers
status: proposed
theme: operations
impact: medium
---

# External IP Tile Contract

## Problem

The system-status strip has five tiles. Four of them are filled from `GET /status` (Nginx path `/status/full`):

```javascript
if (full.vm_ip) document.getElementById('kpi-vm').textContent = full.vm_ip;
if (full.cpu_cores) document.getElementById('kpi-cpu').textContent = full.cpu_cores;
if (full.memory_mb) document.getElementById('kpi-mem').textContent = full.memory_mb.used+'/'+full.memory_mb.total+' MB';
if (full.disk_mb) document.getElementById('kpi-disk').textContent = full.disk_mb.used+'/'+full.disk_mb.total+' MB';
```

The fifth tile is different:

```html
<div class="kpi"><div class="kpi-label">External IP</div><div class="kpi-value" id="kpi-ext">--</div></div>
```

```javascript
if (full.external_ip||full.ip) document.getElementById('kpi-ext').textContent = full.external_ip||full.ip||'--';
```

`status()` returns `vm_ip`, `services`, booleans for six sockets, and optional `load_avg`, `memory_mb`, `disk_mb`, and `cpu_cores`. It does not set `external_ip` or `ip`. `fixtures/status-full-contract.json` does not list those keys. `scripts/validate_status_full_contract.py` does not require them.

A search of the repository for `external_ip`, `EXTERNAL_IP`, `kpi-ext`, and a JSON field named `ip` finds only this landing-page pair. No host script writes a public address into the helper.

The tile therefore stays `--` for every operator, on every refresh.

Checked on 2026-10-05 by reading `nginx/html/index.html` (the KPI markup and `refreshServices`) and `status()` in `helper/uploader.py`, then searching the tree for a writer. The page was not loaded in a browser.

## Existing scan (reuse first)

| Asset | Role |
|---|---|
| `#kpi-ext` | A label with no producer |
| `status()` | The payload `/status/full` already returns |
| `fixtures/status-full-contract.json` | The keys CI treats as the status shape |
| `tu-vm.sh` `HOST_IP` | The LAN address Stage 45 already assigns to `vm_ip` |
| Stage 45 `dashboard-vm-ip-source-contract.md` (expected sibling, open PR #71) | `vm_ip` only. It already rules out a public-address lookup |
| Stage 44 `host-metrics-source-contract.md` (expected sibling, open PR #70) | Load, memory, disk, battery. Not this tile |

Out of scope:

- Filling the tile from a STUN, ipify, or `8.8.8.8` call
- Changing how `vm_ip` is chosen
- Moving memory and disk reads onto the host
- Publishing the VM on a public address

## Proposal

Delete the External IP tile and the two lines that would have filled it. The status strip keeps VM IP, CPU, memory, and disk.

### Contribution lanes

| Lane | Where | Suggested change |
|---|---|---|
| Markup | `#kpi-ext` | Remove the tile |
| Script | `refreshServices` | Remove the `external_ip` / `ip` assignment |
| Helper | `status()` | Leave the JSON as it is. Do not add a public address field |
| Fixture | `fixtures/status-full-contract.json` | Do not add `external_ip` |

### Rules

1. **A tile needs a writer that already exists.** This one has none.
2. **Do not discover a public address from the helper.** The helper sits on `ai_network`. Stage 45 already forbids dialing out to learn an address, and that rule covers this tile too.
3. **Leave `kpi-vm` on the Stage 45 contract.** This page does not change `HOST_IP` or `get_vm_ip()`.
4. **Leave Stage 44 metrics on that contract.** Memory and disk stay where they are.
5. **The status fixture stays the current key set.** Validators should keep failing a payload that drops `vm_ip`, and they should keep ignoring a public-IP key because it is not part of the contract.

### Suggested contributor checklist

```text
1. Read the kpi-ext markup and the refreshServices assignment
2. Confirm status() and the fixture have no external_ip field
3. Remove the tile and the assignment
4. Reload the landing page and confirm the strip no longer says External IP
5. Confirm vm_ip, cpu, memory, and disk still render
6. Do not add an outbound IP lookup
```

### Framework reuse

| Need | Prefer | Avoid |
|---|---|---|
| LAN address | Existing VM IP tile and `HOST_IP` | A second tile plus a new lookup |
| Status shape | `fixtures/status-full-contract.json` | An undocumented `external_ip` key |
| Empty data | Remove the control | A permanent `--` |

## Acceptance criteria

- The landing page has no External IP label and no `kpi-ext` element.
- `refreshServices` does not read `external_ip` or `ip`.
- `status()` does not grow a public-address field.
- The status fixture and its validator stay on the current required keys.
- VM IP, CPU, memory, and disk tiles still bind to the fields they use today.

## Verification notes

Traced the assignment to `full.external_ip||full.ip` on 2026-10-05. `status()`'s `res` dict has no such keys. `rg` over the repo returned the landing page as the only match.

## Rollback

Restore the tile and the assignment. The helper payload is unchanged, so the restored tile shows `--` again.
162 changes: 162 additions & 0 deletions suggestions/website/gateway-public-docs-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
---
title: Gateway Public Docs Contract
description: Constructional contract so oweb.tu.lan publishes MCP and LangGraph liveness only, and detail plus OpenAPI docs require the bearer those apps already check.
last_updated: 2026-10-05
owner: maintainers
status: proposed
theme: security
impact: high
---

# Gateway Public Docs Contract

## Problem

Nginx publishes both apps on the Open WebUI vhost:

```nginx
location /api/mcp/ {
proxy_pass http://172.20.0.26:9002/;
}
location /api/langgraph/ {
proxy_pass http://172.20.0.29:9010/;
}
```

The landing cards say **Internal Only** and print `ai_mcp_gateway:9002` and `ai_langgraph_supervisor:9010`. `status()` and `./tu-vm.sh info` already advertise `https://oweb.tu.lan/api/mcp/` and `https://oweb.tu.lan/api/langgraph/`.

Both processes are created as `FastAPI(...)` with only `title` and `version`. FastAPI then serves `/docs`, `/redoc`, and `/openapi.json` with no dependency. The gateway also has:

```python
@app.get("/health")
async def health() -> dict[str, Any]:
return {
"ok": True,
"affine_enabled": _affine_enabled(),
"n8n_enabled": _n8n_enabled(),
"n8n_mcp_enabled": _n8n_mcp_enabled(),
"kb_enabled": _kb_enabled(),
"write_approval_required": _write_approval_required(),
"allowed_servers": sorted(_allowed_servers()),
"langgraph_supervisor_enabled": ...,
"langgraph_supervisor_url": langgraph_supervisor_url,
"nodeTypesCount": len(_n8n_node_types),
"nodeTypesLoadedAt": _node_types_loaded_at,
}
```

```python
@app.get("/openapi-tools.json", include_in_schema=False)
async def openapi_tools_spec() -> JSONResponse:
```

Neither handler calls `_check_auth`. `/openapi-tools.json` returns every built-in tool name and its input schema.

LangGraph `/health` is also open and returns `strict_verify`, `gateway_url`, and `sorted(WRITE_TOOLS)`.

These callers need a tokenless 200 from `/health` and nothing else:

| Caller | Request |
|---|---|
| Compose `mcp_gateway` healthcheck | `curl -fsS http://localhost:9002/health` |
| Compose `langgraph_supervisor` healthcheck | `curl -fsS http://localhost:9010/health` |
| `scripts/langgraph-e2e-smoke.sh` step 1 | `GET ${BASE_URL}/api/langgraph/health` with no `Authorization` |
| `scripts/langgraph-e2e-smoke.sh` step 2 | `GET /api/mcp/health` with a bearer. The handler ignores the header today |

`/invoke` and `/execute` already require a bearer. `_check_auth` compares `MCP_GATEWAY_TOKEN`. The supervisor's `/execute` compares `LANGGRAPH_SUPERVISOR_TOKEN` or, when that is empty, `MCP_GATEWAY_TOKEN`.

Checked on 2026-10-05 in `nginx/conf.d/default.conf` (the two locations), both `FastAPI(...)` constructors, both `/health` handlers, `openapi_tools_spec`, the Compose healthchecks, and the smoke script. The routes were not requested on a live stack.

## Existing scan (reuse first)

| Asset | Role |
|---|---|
| `_check_auth` | Bearer check for gateway routes that mutate or list tools |
| Supervisor `/execute` token check | The same secret family for LangGraph |
| Compose healthchecks | Must keep succeeding with no header |
| Smoke step 1 | Must keep succeeding with no header |
| `README.md` troubleshooting curls | `docker exec` against `/health` and `/openapi-tools.json` with no header |
| Landing reach tags | Say Internal Only while the vhost publishes the APIs |
| Stage 45 write-tool set (expected sibling, open PR #71) | Which names belong in `WRITE_TOOLS`. This page does not edit that set |
| Stage 45 callback credential (expected sibling, open PR #71) | The `X-LangGraph-Supervised` header. Leave it |
| Stage 42 listener auth (expected sibling, open PR #68) | Filesystem, fetch, memory, and Playwright listeners. Not these two FastAPI apps |
| Stage 41 KB public read (expected sibling, open PR #67) | Unauthenticated KB read tools. Leave that flag |

Out of scope:

- A new login, OAuth server, or dashboard session for MCP
- Moving the proxy off `oweb.tu.lan`
- Changing `WRITE_TOOLS` membership
- Requiring a token on the Compose healthcheck curl

## Proposal

Anonymous `/health` stays a liveness probe. Everything that describes the deployment requires the bearer those code paths already implement. The landing card should name the vhost path operators already use.

### Contribution lanes

| Lane | Where | Suggested change |
|---|---|---|
| Stock docs | both `FastAPI(...)` apps | Set `docs_url=None`, `redoc_url=None`, and `openapi_url=None` |
| Gateway `/health` | `mcp-gateway/app.py` | With no valid bearer, return `{ok: true}` and 200. With a bearer that passes `_check_auth`, return the current object, plus `builtinToolCount` from the catalog-count page |
| Tool spec | `/openapi-tools.json` | Call `_check_auth` before building the spec |
| LangGraph `/health` | `langgraph-supervisor/app.py` | With no valid bearer, return `{ok: true}` and 200. With the bearer `/execute` already accepts, return today's detail object |
| README curls | troubleshooting section | Pass `Authorization: Bearer` from `MCP_GATEWAY_TOKEN` inside `docker exec` when the curl needs `nodeTypesCount` or the tool spec |
| Landing cards | MCP and LangGraph | Replace **Internal Only** with the web path `status()` already publishes (`oweb.tu.lan/api/mcp/` and `oweb.tu.lan/api/langgraph/`). State that calls need the existing token |
| Smoke and Compose | unchanged curls | They only check HTTP success of `/health` |

### Rules

1. **Liveness stays open.** Compose and smoke step 1 keep a tokenless 200 from `/health`.
2. **Detail requires the existing secret.** Do not invent a second docs token. Gateway detail uses `MCP_GATEWAY_TOKEN`. LangGraph detail uses the `/execute` check.
3. **Turn off stock docs.** `/docs`, `/redoc`, and `/openapi.json` are not part of the smoke script or the README curls. Disabling them is the whole change for those three paths.
4. **`/openapi-tools.json` is a catalog, not a healthcheck.** It gets `_check_auth`. Update the README `docker exec` line so operators still can count tools.
5. **Do not edit `WRITE_TOOLS`.** Hiding the list on anonymous `/health` is the change. Which names are in the set stays on the Stage 45 page.
6. **Do not lock the four MCP tool listeners here.** That is the Stage 42 listener page.
7. **Do not flip `KB_PUBLIC_READ_ENABLED`.** Anonymous KB reads stay on their own contract.
8. **The reach tag matches the vhost.** The cards stop saying Internal Only for routes Nginx publishes on `oweb.tu.lan`.

### Suggested contributor checklist

```text
1. Confirm Compose healthchecks and smoke step 1 use tokenless GET /health
2. Disable FastAPI docs, redoc, and openapi_url on both apps
3. Return {ok: true} from both /health handlers when the bearer is missing
4. Require _check_auth on /openapi-tools.json
5. curl /api/mcp/docs and /api/mcp/openapi-tools.json without a token and expect 404 and 401
6. curl both /health URLs without a token and expect 200 and a body of {ok: true}
7. Repeat /health with the existing bearer and expect the detail fields
8. Update the README docker exec lines that need those fields
9. Point the two landing cards at the oweb.tu.lan paths
10. Do not add a new auth service
```

### Framework reuse

| Need | Prefer | Avoid |
|---|---|---|
| Gateway auth | `_check_auth` | A new middleware stack |
| Supervisor auth | The `/execute` bearer check | A second token name |
| Liveness | Existing Compose `curl` of `/health` | Putting the token into the healthcheck |
| Tool spec | `/openapi-tools.json` behind that bearer | Stock `/docs` left on the vhost |
| Card label | The URL `status()` and `tu-vm.sh info` already print | A new hostname |

## Acceptance criteria

- `GET /api/mcp/health` and `GET /api/langgraph/health` with no token return 200 and a JSON object whose only field is `ok: true`.
- The same URLs with the existing bearer return the detail fields those handlers return today.
- `GET /api/mcp/docs`, `/api/mcp/redoc`, and `/api/mcp/openapi.json` are not served.
- `GET /api/mcp/openapi-tools.json` with no token returns 401.
- The same URL with `MCP_GATEWAY_TOKEN` returns the spec.
- Compose healthchecks remain tokenless `curl` commands and still treat HTTP 200 as healthy.
- Smoke step 1 stays a tokenless health GET and still passes on HTTP success.
- The MCP and LangGraph cards no longer say Internal Only. They show the `oweb.tu.lan` API paths.
- `WRITE_TOOLS`, the supervised-call header, and `KB_PUBLIC_READ_ENABLED` are unchanged.

## Verification notes

Read the FastAPI constructors, both health handlers, `openapi_tools_spec`, the Nginx locations, the Compose healthchecks, and smoke steps 1 and 2 on 2026-10-05. No request was sent to a running stack.

## Rollback

Restore the FastAPI defaults and the full anonymous health bodies, and restore the Internal Only tags. Compose healthchecks stay valid either way.
Loading
Loading