# Proxy Manager

Nginx Proxy Manager inside Officer — which hosts are running, whether they are healthy, and which
certificates are about to expire.

**Status: first round. Reads work against a live NPM 2.15.1; the settings form is not built yet** —
see "What is not built" below.

---

## Why it is called `proxy-manager` and not `npm`

The container is called `npm` and everybody says NPM. But in a repository where every other sentence is
about bun, lockfiles and `npm install`, a plugin directory called `npm` collides with the package
manager in every grep and every conversation. The label says the real name; the id says what it does.

The same reasoning renamed `officer-claude` to `officer-anthropic-proxy`. Trivial to change while
nothing depends on it.

---

## What it does

**Hosts** — every proxy host, sorted by domain, showing where it forwards, whether TLS is on and
forced, whether an access list guards it, and whether nginx currently reports it offline. Selecting one
lets you take it out of service or put it back.

**Certificates** — sorted by how soon they expire, not by name. That ordering is the whole design: a
list sorted by name is a reference, a list sorted by expiry answers the only question anyone has.
Under 30 days is amber, under 14 is red, because Let's Encrypt renews at 30 and anything inside 14 means
renewal has actually failed.

Redirection hosts, streams, 404 hosts and access lists are exposed by the API and not yet drawn.

---

## What it deliberately does not do

**No creating, editing or deleting hosts. No certificate issuance.** NPM's own UI does those well and is
one click away, and each is a form with real consequences — a wrong proxy host takes a domain off the
internet.

This surface answers *"what is running, and is it healthy"*, and the one write it allows is reversible in
a click. Building the editor is a decision to make deliberately, not to arrive at by accretion.

---

## Permissions

One permission, `proxy-manager`, and it is **grantable**. Reading which hosts exist and whether their
certificates are healthy is genuinely useful to somebody who is not the owner.

The credential is not. It is an NPM admin login, NPM has no read-only role, and anyone holding it can
redirect any hostname this machine serves. So `/_config` is `ownerOnly` — the split that field exists
for, and the same shape Jellyfin uses for its admin token.

**The secret is never returned across the API boundary**, at any level, to anybody, including the owner.
A settings form asking "is one set" gets a boolean.

---

## The connection

One row in `proxy_manager_connection` — URL, identity, and a secret encrypted under this plugin's own
purpose key (`encryptSecret('proxy-manager', …)`), so a leak of that key opens this column and nothing
else.

**One row, not one per user.** NPM's API is admin or nothing, so a per-user credential would be a
per-user copy of total authority over every hostname on the machine. The owner sets it; members granted
the permission read through it without ever seeing it.

It is a plugin-owned table rather than core `service_connections` — which fits the shape exactly, with
`url`, `username` and an encrypted `secret` — only because `ServiceName` there is a closed TypeScript
union, and this plugin should install into a platform it did not have to edit. Worth revisiting if that
union opens; `db/schema.ts` says so.

---

## The API quirk that shapes this plugin

**NPM answers an unauthenticated read with 404, not 401.**

```
GET /api/nginx/proxy-hosts  ->  {"error":{"code":404,"message":"Not Found - /nginx/proxy-hosts"}}
```

Its router only registers a resource once the request carries a token, so *"not signed in"* and *"no such
endpoint"* are the same response. Left alone that produces the worst kind of bug report: a feature that
reads as missing when the credential is simply wrong.

So `npm-client.ts` treats a 404 on a path it knows exists as an authentication failure, carries that as
`NpmError.likelyAuth`, and the panel turns it into a sentence pointing at settings. It also mints a fresh
token and retries once before concluding anything — otherwise a restarted NPM makes every panel look
broken until a reload.

Verified against the live instance: a wrong credential comes back `likelyAuth = true`, and
`POST /api/tokens` answers **400 "Invalid email or password"** rather than 401.

---

## What is not built

- **The settings form.** `/_config` works — `GET`, `PUT`, `DELETE`, and `POST /_config/test` which
  checks a credential *without storing it*, so a wrong password never replaces a working one. Nothing
  renders it yet, so the connection has to be inserted by hand for now.
- **`db:push` has not been run**, so `proxy_manager_connection` does not exist in Postgres yet.
- **Redirections, streams, 404 hosts and access lists** have routes and no panels.
- **Nothing is polled.** Both panels load once and have a refresh button.
- **No tests.** The client's behaviour was verified by hand against the live NPM; that should be a test
  with a stubbed fetch.

---

## Files

```
manifest.ts          permission, ownerOnly, readOnlyWrites
api/npm-client.ts    tokens, the 404 quirk, retry
api/connection.ts    the one row; encryption; the secret never leaves
api/router.ts        mounted at /api/proxy-manager
db/schema.ts         proxy_manager_connection
web/panels.ts        two panels
web/layout.ts        how they are arranged
```