pastilhas
2acd103750
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.
Linkwarden
Your bookmarks, behind an Officer session. One self-hosted Linkwarden per Officer install, pointed at by the owner, with every Officer user mapped onto an account of their own.
Officer stores no bookmarks. Linkwarden owns those. What this plugin owns is the credential and the door.
The model
It is the Vault model, and deliberately so:
| One instance per install | linkwarden_config, one row pinned by a CHECK, set in the panel. Not .env — a plugin cannot ask the owner to edit a file and restart a process. |
| A sidecar owns the upstream | officer-linkwarden reads the URL from Postgres with a short TTL and reverse-proxies. Nothing else knows where Linkwarden is. |
| Two doors | An authenticated one for Officer's own UI, which injects the mapped user's token so the device never holds one. And /api/linkwarden/lw, unauthenticated, for the browser extension — which carries its own credential and has nowhere to put an Officer JWT. |
| A mapped account per user | linkwarden_accounts. This is the part Vault does not have; its schema says so outright. Provisioning follows ../USER_PROVISIONING.md. |
The one thing that is not like Vault
Vaultwarden speaks a host-agnostic bearer protocol. Linkwarden is a Next.js app using NextAuth.
That difference is the whole of the difficulty. NextAuth issues host-scoped session cookies, checks CSRF
against the host, and hands clients absolute URLs built from NEXTAUTH_URL. Measured on the live
instance rather than inferred — a sign-in posted to 100.64.0.1:3000 answers with:
{"url":"https://linkwarden.home.pastilhas.eu/api/v1/auth/signin?csrf=true"}
So serving the extension through Officer requires NEXTAUTH_URL to name the address Officer serves it
at. That is a change to the container, not to this plugin, and it is a prerequisite rather than a
preference: leave it and the extension is bounced out of the proxy mid-login, to a host that in this case
does not even answer.
The API half is unaffected. /api/v1/* accepts Authorization: Bearer <access token> and never touches
NextAuth, so the panel — and anything an agent does — works either way. Only the extension's login
depends on it.
Verified against the live instance
Linkwarden v2.16.2, 2026-09-05. Every status below was observed, not read in a doc.
| Route | Without a token | With a token |
|---|---|---|
/api/v1/dashboard |
401 | 200 |
/api/v1/collections |
401 | 200 |
/api/v1/tags |
401 | 200 |
/api/v1/links |
401 | 200 |
/api/v1/users |
401 | 200 — the admin surface, used for provisioning |
Shapes worth knowing before reading the code:
- collections — nested through
parentId, withisPublic,ownerIdandmembers. - tags — paginated,
{ tags, nextCursor }, unlike the others. - links — carry the archive:
textContentandreadable(extracted text), pluspreview,image,pdfandmonolith, withlastPreserved.textContentis the reason this is worth more than a bookmark bar: it makes a saved link something that can be searched and quoted rather than re-opened.
State
Foundation only. manifest.ts, db/schema.ts and this file. The sidecar, the routers, provisioning and
the panel are not written yet.