`createSidecarProxy` is for AUTHENTICATED proxying. Its forwarder does
`ctx.get('user').id`, because every other sidecar behind it is reached by
somebody holding an Officer session. This door is declared in
`unauthenticatedPaths`, so there is no user, and mounting the factory's router
there answered every request with `TypeError: undefined is not an object` as a
500.
Found on alpha with a real request rather than by reading: the authenticated door
returned 401 as it should and the extension door returned 500.
Vault hand-writes its public router for exactly this reason. I reached for the
shared thing because it was shared, which is the wrong reason - it is shared
among routes that have a caller, and this one deliberately does not.
The factory is still constructed and still earns it: getHttpUrl(), so the port
the sidecar announced is learned in one place, and registerProxiedPrefix, which
runs at construction and keeps the body parser off /api/linkwarden/lw. Neither of
those is the router.
`/config` is owner-only and takes a PUT, so without this the only way to point
the install at a server was curl. A plugin cannot ask that - installing it has to
be enough, which is the same argument the schema makes for the URL being a table
rather than an env var.
`web/panels.ts` and `web/layout.ts` are required once `web/` exists, and the
directory existed empty, so discovery would have refused the plugin with exactly
that complaint.
The panel says the thing this install taught me, at the point where it would
otherwise be rediscovered: the address it asks for is the one the SIDECAR dials,
not the one a browser or the extension is given. Those are the same string on
most setups and are not here - the name Linkwarden advertises resolves to
127.0.1.1 on the host it runs on, where nothing is bound.
The admin token is write-only across the boundary: never sent back to the screen,
and only sent on save when something was typed, because an empty field means
"leave it alone" rather than "clear it".
Health has three distinct reasons - unconfigured, unreachable, sidecar not
running - because they are three different next actions and one word for all of
them sends somebody to check the wrong thing.
Officer holds the credential; Linkwarden holds the data and decides who may see
it. That split is the whole design and it is why there are two doors that look
alike from outside and are not.
`/lw/*` is the extension's. Unauthenticated, forwarded verbatim, the credential
is the caller's own - the same argument Vault's public router makes, that this is
one address instead of two rather than new exposure, and it is what lets
Linkwarden stop being reachable on its own.
`/api/*` is ours. An Officer session names the caller, we find their mapped
account and put THEIR token on the request. A browser holding an Officer session
never holds a Linkwarden credential, which is the property Vault exists to give,
applied per user. Officer decides whose token goes on; Linkwarden decides what it
may see, because re-implementing that here would be a second answer able to
disagree with the first.
`proxiedSubPath: '/lw'` is load-bearing rather than tidy. Claiming the whole
prefix would tell the body parser to leave /config alone too, and every field on
it would read as missing - the failure caldav hit the day it was extracted.
The sidecar is a plain HTTP proxy with no WebSocket: Vaultwarden pushes over
SignalR and Linkwarden does not, so a socket here would be scaffolding for a
protocol that does not exist. Its onCommand is empty for the same reason - it
forwards bytes, and everything that decides anything happens before a request
reaches it.
Two things measured rather than assumed while writing this. The port announcement
typechecks because SidecarPortAnnouncement was generalised, so a plugin no longer
needs a platform pull request to announce its own port. And the config URL is the
LOOPBACK address, not the advertised one: on alpha the name Linkwarden now
advertises resolves to 127.0.1.1, where nothing is bound, so a sidecar running
there would dial the name it publishes and get nothing.
Typechecks clean. No provisioning and no panel yet.
One Linkwarden per Officer install, pointed at by the owner, with every Officer
user mapped onto an account of their own. Officer stores no bookmarks; it owns
the credential and the door.
The model is Vault's, and the parts that are the same are the same on purpose:
a one-row config table rather than an env var, because a plugin cannot ask the
owner to edit a file and restart a process; a sidecar that is the only thing
knowing where the upstream is; and two doors, one authenticated for our own UI
and one unauthenticated for a client that carries its own credential.
`linkwarden_accounts` is the part Vault does not have. Its schema says so in as
many words - "mapping Officer accounts onto them is not a column here" - so this
is new work rather than a copy, and it follows plugins/USER_PROVISIONING.md,
written from the photos plugin against Immich.
── The difference that matters ──
Vaultwarden speaks a host-agnostic bearer protocol. Linkwarden is a Next.js app
using NextAuth, which issues host-scoped cookies, checks CSRF against the host,
and hands clients absolute URLs built from NEXTAUTH_URL. Measured rather than
inferred: a sign-in posted to the tailnet address answers with an absolute URL
to a hostname that does not answer at all.
So serving the extension through Officer needs NEXTAUTH_URL to name the address
Officer serves it at. That is a change to the container rather than to this
plugin, and it is a prerequisite, not a preference. The API half is unaffected -
/api/v1/* takes a bearer token and never touches NextAuth - so the panel and
anything an agent does work either way.
Verified against Linkwarden v2.16.2 on 2026-09-05: every route 401 without a
token and 200 with one, including /api/v1/users, which is the admin surface
provisioning needs. Links carry textContent and readable, which is what makes a
saved page searchable rather than merely re-openable.
Foundation only. No sidecar, routers, provisioning or panel yet.
pastilhas