# 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 and the plugin is not installed** — 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. `POST /_config/test` is owner-only too, and that is on purpose rather than by accident of the prefix match. It is a genuine read-only write — it validates a credential and stores nothing — but the request carries the admin secret in its BODY, so a member who could call it would have an oracle pointed at somebody else's password. Testing a connection belongs to whoever owns it. (Declaring it in `readOnlyWrites` would also have done nothing: `authorize.ts` asks `isOwnerOnlyRoute` first.) --- ## 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. Both halves of that — the rule and the single retry — are the plugin's most load-bearing behaviour and its only tested one: `api/npm-client.test.ts` covers them against a stubbed fetch, because a refactor of either fails silently and turns a working panel into one that says "not found" forever. 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. `GET /status` is built to be polled when something does: the probe is cached for 30 seconds and the row is written only when the verdict or the version changes, so a poll is not an UPDATE. - **It is not installed.** `plugin_installs` has no row for it and `proxy_manager_connection` does not exist in Postgres, so nothing here has been through the permission gate, `assertPermissionTotality` or a real request. The reads were verified by direct invocation against a live NPM 2.15.1. --- ## Files ``` manifest.ts permission, ownerOnly api/npm-client.ts tokens, the 404 quirk, retry api/npm-client.test.ts 22 tests over a stubbed fetch 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 ```