proxy-manager/README.md

# Proxy Manager

Hand your proxying over to Officer, and tell it what you want in a sentence.

**Status: first round, and built to the wrong thesis.** Reads work against a live NPM 2.15.1. The brief
that produced this code was, in full, "build me an NPM proxy" — no vision was given, so the agent that
wrote it inferred a sensible one and inferred it wrong. What is below under "What this is for" is the
actual intent, written down after the fact. Read that before extending anything.

---

## 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 this is for

Not a second window onto Nginx Proxy Manager. NPM already has a perfectly good one.

The point is to let someone hand over the parts of this they would rather not think about, and to make
handing over safe enough that it is a reasonable thing to do. There are two paths and the setup should
ask, out loud, which one you are on.

**You hand over the credentials.** Your NPM login, and your DNS provider's API key — GoDaddy,
Cloudflare, whoever you registered with. Both go into the secret store, each encrypted under its own
purpose key, and neither is ever returned across the API to anybody, including you. From then on you ask
for what you want in a sentence — *"expose sub.mydomain.com on the tailnet, over HTTPS"* — and an agent
does the three things that sentence actually means: the DNS record, the certificate, the proxy host.

**You keep them.** Then you run NPM yourself on a public address and handle DNS at your provider. That
is a completely reasonable way to run a server, and if it is you, this plugin has little to offer: a
list you already have, plus a certificate warning you could set up yourself.

Which is the honest test of whether this should exist at all. **It exists for the handover.** Everything
here is worth building in proportion to how much it helps somebody who does not want to learn what a
proxy host is — and it should still be legible to somebody who has been doing this by hand for years,
because that person is who decides whether the handover looks safe.

## Why a private name needs your DNS key

The clearest case, and the one that shows the credential is a requirement rather than a nice-to-have.

HTTPS needs a certificate. Let's Encrypt issues them free, but only after checking you control the name,
and normally it checks by visiting it over the internet. A name that resolves to a tailnet address
cannot be visited. There is exactly one other check it accepts: prove control by placing a specific
record in that domain's DNS — which needs the provider's API.

So **TLS on a VPN-only hostname is impossible without the credential.** That is not a limitation of this
design, it is the shape of the problem. The alternative is not "the same thing without a key", it is a
publicly exposed address with DNS you manage yourself.

## How the agent asks, and what it is never told

The agent calls **this plugin**, and never Nginx Proxy Manager. Keeping up with NPM's API — its version,
its shape, the day it changes — is this plugin's job, and the whole point of having one.

Most of what it exposes is a thin proxy over NPM's reads, and should stay thin. **The expose route is
the one place it deliberately is not.** The agent sends what was asked for — a hostname, what it should
point at, and which network may reach it — and the plugin turns that into the three separate things it
actually means: a DNS record, a certificate, a proxy host.

That split is the whole safety argument. "Reachable only from the private network actually means these
three things" gets written down once, here, where it can be read and tested. The alternative is teaching
the agent NPM's own request format, which puts that knowledge in the agent's memory instead — and you
would discover it had forgotten only when a hostname is reachable that should not be.

The agent is never given a credential. Not NPM's, not the DNS provider's. It says the sentence; the
plugin holds the keys and does the work.

## "Private" is a network the user names, not a tailnet

Officer can set up a Tailscale network for you, and it knows that network's address range — so it can
fill this in without asking. **That is a convenience, not the model.** Somewhere with a VPN already in
place has their own ranges and nothing to do with Tailscale, and they must be able to say so.

So what gets stored is a **named network and the addresses it covers**, and the request is *"expose this
to <name>"*. NPM's access lists take address ranges, so this costs nothing to support properly.

The certificate half is unchanged by any of it. What forces the DNS proof is that the name cannot be
reached from the public internet — true of anybody's private network, whoever runs it.

## Read-only is a state, not the design

The first round creates nothing, edits nothing and deletes nothing, and the original README argued that
as a principle: NPM's own UI does those well, and each is a form with real consequences.

Half of that survives. **Creating is additive** — a new proxy host cannot break one that already works —
so it is the write path the agent should get, and it is the product rather than a later phase. **Editing
and deleting are not**, and those can stay in NPM's UI until there is a reason they should not.

Read-only is what the plugin shows before anyone has handed anything over. It is the fallback, not the
thesis.

## 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.
- **All of the above.** No domain registry, no DNS provider credentials, no named networks, no agent,
  no expose route. Everything from "What this is for" through "Private is a network the user names" is
  agreed and entirely unbuilt.
- **One thing left to check before building the DNS half.** Whether a given GoDaddy account still has
  DNS API access — they restricted it by account size at some point, and it is unverified here.
  Cloudflare is the safer provider to build against first.

  The other half of this is now answered: **NPM tells you which providers it can drive**, over
  `GET /nginx/certificates/dns-providers`, and it hands back each one's credential field names as a
  template. 86 providers on the 2.15.1 image. So the picker asks the instance rather than trusting a
  list of ours, and the form is generated from what NPM says. See `docs/npm-api.md`.
- **Certificate expiry notifies nobody.** `daysUntilExpiry` is computed in `api/router.ts` and thrown
  away when the panel closes. NPM renews at 30 days; inside 14 means renewal has actually failed and the
  domain goes dark at zero. Nothing on the machine will say so.
- **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
```