A list of titles and addresses is what a browser's own bookmark bar does. The
reason to keep pages here is that they have been fetched and archived, and a
grid of covers is the cheapest way to show that.
── Which picture, and the trade it costs ──
A crawled bookmark carries two: `content.imageUrl`, the page's own og:image, and
a `screenshot` asset Karakeep took and stores itself. The screenshot is better -
archived, cannot rot, never leaves the house - and it is unreachable from an
`<img>`: Officer authenticates with a bearer token in a header and a browser
cannot put a header on an image request, so the asset route answers 401 from
markup. Fetching each as a blob would work and costs a request, a decode and an
object URL per card.
So the origin's image, with referrerPolicy="no-referrer" so those sites learn
nothing about where the request came from, and loading="lazy" so a long grid does
not fetch a hundred at once. The honest cost, written at the point of use:
viewing your bookmarks makes requests to the sites they point at. Proxying the
archived asset is the fix if that ever matters.
── The empty state is three states ──
Not crawled yet, crawled with nothing to find, and a picture that failed to load.
The first is temporary and the others are not, so it says "fetching…" and the
header counts how many are still going. Measured on the live instance while
writing this: 6 of 50 crawled, the rest pending - so a fresh import spends a
while looking like a broken panel unless it explains itself.
Grid is auto-fill on a minimum width rather than a column count, because this is
one pane of a layout the owner can drag and the columns have to follow the width
it is actually given.
Same model as Vault: one instance per install, a sidecar that is the only thing
knowing where it is, two doors - one authenticated for our own UI that injects
the caller's credential, one unauthenticated for a client that carries its own -
and an account per Officer user.
── Why this upstream ──
Linkwarden authenticates its extension through NextAuth: host-scoped cookies,
CSRF checked against the host, absolute URLs baked from NEXTAUTH_URL. Proxying
that means telling the upstream the address the CLIENT uses, which is not the
address the SIDECAR dials, and getting it wrong bounces the extension out of the
proxy mid-login. It cost a NEXTAUTH_URL change, a container recreate, a lost csrf
cookie, and it retired the upstream's own web login as the price of going through
Officer.
Karakeep's extension holds an API key and sends it as a header. Nothing is
host-pinned, so none of that exists. And provisioning needs nothing pasted:
users.create and apiKeys.exchange are both public procedures, so Officer creates
the account, chooses the password, and mints the key itself - where Linkwarden
could only take a key a person made by hand.
── Carried over deliberately ──
Two fixes from the Linkwarden build, both upstream-agnostic and both found by
running it rather than reading it. `content-encoding` stripped from proxied
responses, because fetch decompresses the body while the headers still claim
gzip - which hides until the first response big enough to compress. And
Set-Cookie copied with append rather than set, because it is the one header that
legitimately repeats. Karakeep should never need the second one; it is here
because a proxy correct only for the traffic its author tested is a trap for
whoever changes the upstream later.
Also carried: the unauthenticated door is hand-written rather than the shared
createSidecarProxy router, which does ctx.get("user").id and 500s where there is
no session.
Written against source, not yet run. The response shapes in the panels come from
packages/api/routes/ and are the first thing to check against a live instance.
No provisioning yet.
pastilhas