API reference, OpenAPI spec, and a coverage test that can fail (#51)

[CaYatur]

Closes #51.

Three descriptions of the integration surface, all generated from one table
(src/shared/apiSurface.ts):

docs/openapi.json	machine-readable OpenAPI 3.1, checked in
GET /api/v1/openapi.json	the same document, served by the app
GET /api/v1/docs	a self-contained reference page
docs/api-reference.md	the human entry point, linking the prose docs

The part worth reviewing: the coverage test

#51 asks that every /api/v1 route appear in the spec. The obvious way to check
that cannot fail — a test that walks the spec's own paths and confirms each
one exists only finds routes that were documented and then deleted, never the
reverse, which is the failure that actually happens.

So the assertion reads the route literals out of handlePanel's own source
(path === '/api/…', sub ===, action ===, rest ===) and requires the
table to document each one — then checks the other direction, so the table
cannot invent a route either.

It found GET /servers/:id/store/admin/ledger on its first run: undocumented
since it shipped. That is the evidence the test is not vacuous.

Serving it unauthenticated

The index, the spec and the docs page are the only routes answered before
authentication. All three are descriptions of the software, built from a
constant table — and the smoke asserts that neither the spec nor the page
contains this install's server id or name, so "no credential" stays a
convenience rather than a disclosure. Requiring one would also make the docs page
useless to the thing that needs it most: a browser, which cannot set an
Authorization header on a navigation.

No CDN, no Swagger bundle: the panel's CSP forbids external assets, and
documentation that needs an internet connection is a poor way to document a LAN
tool. Asserted.

Deliberate

Body shapes are prose in each operation's description, not sixty invented JSON
schemas — sixty more things to keep true, when what an integrator needs is the
method, the path, the gate, and what the call does.

Verify

All twelve gates exit 0. MSMS_SMOKE_WEB checks: the v1 rewrite answers
identically to the unversioned path and is anchored (/api/v2 is not v1), the
served spec is byte-identical to the generated one, coverage in both directions,
no install data in either artefact, and no external asset on the page. It also
rewrites docs/openapi.json, so the checked-in copy cannot go stale.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[CaYatur]

Self-review

I added three unauthenticated routes to the panel listener and made two of
them expensive.

The per-IP token bucket from #50 is wired into handleSite only. On the admin
listener the only pre-auth guard is rateLimited(ip) on /api/login. So as
written, /api/v1/openapi.json rebuilt a ~120 KB object graph and stringified
it per request, with no credential and no limit — anyone who can reach the
port gets to spend the event loop, which is precisely the shape of thing #50
exists to stop. /api/v1/docs was the same, smaller.

Two fixes, because either alone is half a fix:

• Built once. Both derive from a constant table, so the output cannot change
  while the process runs. Serving is now a buffer write.
• Limited per address, sharing the bucket the public storefront reads spend
  from, so even a buffer write has a ceiling.

Also Cache-Control: public, max-age=300 instead of no-store: these are
descriptions of the software, and telling a client never to cache them was
wrong on its own terms.

Asserted: twenty consecutive fetches must all return the identical body and
average under 25ms each. Before the fix that loop measured the real cost; the
threshold is the assertion, not the comment.

Not fixed here, and worth stating rather than leaving implied: getPanelHtml()
and getPublicSiteHtml() also rebuild their whole string per request, and the
panel page is likewise unauthenticated. That is pre-existing and larger than
this PR — flagged, not smuggled in.

All twelve gates green after the fix.