Gitea's inline script carries `appUrl: 'https:\/\/gitea.example.com\/'`, and
rewriteAbsolute only matched the literal `https://` form. So appUrl survived
pointing at the real host while every visible link was rewritten correctly.
The failure was quiet rather than obvious: the page rendered, and only the URLs
Gitea's JS BUILDS from appUrl went wrong — cross-origin to the real host,
answered with its login HTML. The heatmap reported "Unexpected token '<'" while
parsing JSON, and the event worker failed the same way.
Third instance of the same class today, after the asset paths and appSubUrl: a
URL hiding in a shape the rewriter did not think to look for. All three were
found by loading the page, none by the tests — and all three now have a test
written against a live sample rather than an imagined one.
Gitea inlines a script naming its own worker:
'\/assets\/js\/eventsource.sharedworker.…js'. That is not an attribute and its
slashes are backslash-escaped, so neither the attribute rewrite nor appSubUrl
saw it. Unprefixed, the browser resolved it against the PLATFORM's origin, got
the SPA's index.html, and reported "Uncaught SyntaxError: Unexpected token '<'"
from a file that appeared to load — along with a dead SharedWorker and a
heatmap parsing HTML as JSON.
appSubUrl covers everything Gitea's code BUILDS at runtime. This covers what is
already in the page before that code runs.
Narrow on purpose, like dev-proxy's /_bun/ rule: a blanket rewrite of absolute
paths inside JavaScript corrupts strings that are not URLs. /assets/ is Gitea's
own asset root and specific enough to match safely.
The escaping has to match the string it lands in — \/api\/gitea\/_web, not
\\/api — or the JS stops parsing. Both forms are tested against a live sample.
The minted tokens lived in an in-memory Map, so every restart of the platform
silently invalidated every open frame: the browser kept sending a cookie that
matched nothing and the frame answered 401 mid-session with "no gitea frame
session". Deploying anything at all logged everyone out of the iframe — which
is exactly how this was found, a restart landing between a sign-in and the POST
that followed it.
An HMAC over the account and an expiry needs no state, so a restart changes
nothing. Same shape api/browser/relay-auth.ts already uses, and the same key —
getKey('jwt') from the secret store, which persists.
Compared with timingSafeEqual, because comparing a signature with === leaks how
much of it was right.
Gitea needs allow-same-origin to keep a session and allow-scripts for the
interface to work, and those two together give back everything sandbox takes
away. The browser says so on every load: "an iframe which has both
allow-scripts and allow-same-origin can escape its sandboxing."
So it was decoration that emitted a warning nobody can act on, which is how
people learn to ignore warnings. What actually stands here is that this is
Gitea's own interface, on the platform's own origin, through a proxy the
platform wrote.
Bun's fetch sets its own Accept-Encoding and decompresses transparently, so
upstream.body is plain while upstream.headers still says gzip. Passing both on
hands the next hop a body that contradicts its own header, and it dies with
ZlibError.
Fixed for the HTML branch and missed on the pass-through, so the page rendered
while every stylesheet, script and image beside it answered 502 — which reads
as a broken asset pipeline rather than one header on one branch.
Every asset in the frame answered 502. `fetch()` decompresses transparently
while `upstream.headers` still claims content-encoding: gzip, so re-emitting
those headers with the decompressed body hands the next hop a lie and it dies
with ZlibError.
The HTML escaped it only because the sidecar deletes that header when it
rewrites — which is why the page rendered and every stylesheet, script and
image beside it failed.
Not asking for compression removes the mismatch rather than chasing it through
two hops. The cost is nil: this hop is loopback, and the browser's own
connection is compressed by whatever terminates TLS.
The regex expected JSON — "appSubUrl":"…" — and Gitea emits a JavaScript object
literal: unquoted key, single quotes, `appSubUrl: ''`. So the single
highest-value rewrite in this file silently did nothing on every real page,
while every attribute around it rewrote perfectly.
The test used the shape I guessed rather than the shape Gitea produces, which
is why it passed. Now covers both, with the real form taken verbatim from a
live response, and asserts the quote style survives — swapping it would stop
the literal parsing.
`.text()` decompresses, so the rewritten HTML goes back plain — while the
headers still said `content-encoding: gzip`. The next hop believed the header,
tried to gunzip plain text, and failed with ZlibError.
Which surfaced as "gitea unreachable": a 502 naming nothing, while a direct
curl to the sidecar returned 200 the whole time.
'gitea unreachable' on its own is not a diagnosis. The sidecar was answering
200 to a direct curl while the panel showed that message, which sent the search
to the wrong half of the system twice.
The frame answered {"error":"internal error"} on every request. The cause was
AES-GCM failing with "Unsupported state or unable to authenticate data" — the
token in service_connections was encrypted under a key that no longer exists,
because the platform mints its encryption key on first use and does not back it
up. The same loss took slskd, memos and gitea credentials on this project's own
server earlier today.
It presented as a broken sidecar. connectionState reported `configured: true`
because a ROW exists, so the panel skipped the form and went to the frame,
where every call threw. Nothing offered a way to fix it, and the connection
form was unreachable precisely because it only appears when unconfigured.
Now a named failure. `UnreadableCredentials` is distinguished from every other
error — a database that is down keeps its own message, or a real fault would be
reported as "re-enter your token" — and the panel shows the form saying the key
changed, nothing else is lost, and the URL is still there.
Verified by the platform itself refusing to decrypt: this is the state that
machine has been in all day.
/session and /_web/* were both dead. createSidecarProxy registers all('/*')
when it is CALLED, so anything added to proxy.router afterwards never matches —
hono goes in registration order and the wildcard had already claimed
everything.
The symptom was `[gitea] proxy POST /session -> 500`: forwarded to a sidecar
with no such route, answered "internal error", and looking exactly like the
sidecar being broken. Which is what the panel showed.
A comment two lines above the bug claimed these were "registered BEFORE the
proxy's /*". They were not, and writing that down did not make it so.
Now a router of our own with the proxy's mounted under it at the end, so
everything above genuinely wins.
The dependency this plugin actually wants, and the reason the platform grew
release dependencies: tea is not in any distribution, and Debian has an
unrelated package of that name — a graphical text editor. `packages` is empty
on purpose, because every entry in it would install the wrong program.
`identify` runs `tea --version` and looks for `go-sdk`, which Gitea's CLI
prints and the text editor does not. Bun.which cannot tell them apart, and a
namesake reported as satisfied is worse than one reported missing.
Pinned at 0.15.1 rather than latest: an install that silently fetches whatever
is current is not reproducible.
Deleting the old UI took its connection panel with it, so the plugin installed,
opened, and had nowhere to type a URL. The frame would have loaded and answered
503 on every request inside it — which reads as Gitea being down rather than as
nobody having said where Gitea is.
The panel now asks for the connection FIRST and shows the form when there is
none.
Two halves, and which one you get depends on who you are: the URL is the
owner's, one instance per server, and everyone else supplies only a token and
inherits it. Not a UI choice — service_connections stores a member's row with a
null URL for exactly this reason, so "members never see the instance URL" is a
property of the schema rather than a filter somebody has to remember.
Defaults to http://localhost:3000 and says why in the field: the sidecar
fetches SERVER-side, so localhost means the machine Officer runs on. It needs
no TLS and never leaves the box, where the public URL takes the same traffic
out and back.
Gitea believes it lives at /. Its pages are full of root-absolute links, and
inside the frame those resolve against OFFICER'S origin — the page renders
perfectly and falls apart on the first click.
Four places a URL hides, each failing differently: href/src/action attributes,
window.config.appSubUrl, Location headers, and absolute URLs built from
ROOT_URL.
appSubUrl is the highest-value line. Gitea already supports being hosted under
a subpath and its client JS prefixes every URL it builds with that value, so
filling it in makes Gitea correct ITSELF rather than by interception.
The ROOT_URL case needs Gitea's public origin, which the sidecar does not have
— it fetches from loopback. Rather than add a second setting that can disagree
with Gitea's own, appUrlOrigin reads it out of the page: Gitea emits "appUrl"
in the same config blob as appSubUrl.
Not rewritten, deliberately: JavaScript bodies, because a blanket rewrite of
absolute paths inside a script corrupts strings that are not URLs; and clone
URLs, which must keep working for whoever copies them.
/_web/* now forwards by hand rather than through createSidecarProxy. That
forwarder passes three headers and nothing else, on purpose — it is shared by
every sidecar and its restraint is what makes it safe to reuse. It strips
cookies, and this path is nothing but cookies. Loosening it for gitea would
loosen it for the wallet.
Eighteen tests, the only part of this plugin verifiable without a running
Gitea. One caught a real bug: rewriteAbsolute turns a full URL into <base>/path
and the attribute pass then prefixed it again.
Eleventh plugin out, and the first that is not a move. The seventeen files that
reimplemented a fraction of Gitea's interface were deleted rather than carried
across — each one a promise to keep pace with a project that moves faster than
this plugin will.
That removed a platform change nobody now has to build. useGiteaLocation read
:owner/:name/:tab/:item from five route patterns and a plugin gets two, so
extracting as-is would have needed the plugin system to declare extra routes.
Nothing inside an iframe needs a route, so the requirement went with the screen.
No regression window: gitea's router had been commented out of hono.ts since
2026-08-13 with api: [], and officer-gitea was running nowhere. The screen
rendered and every request 404'd.
The proxy is what makes the iframe possible, not decoration. Officer and Gitea
are different registrable domains, so a frame pointed straight at the instance
gets a login page whose cookie the browser drops as third-party. Through
Officer's origin it is first-party and survives; X-Frame-Options and CSP are
stripped, safe only because the frame is the origin the browser already
authenticated.
/_web/* forwards the browser's own cookies and injects NOTHING. The sidecar
holds an API token and injecting it there would show every user the owner's
view of every repository. It is used only by /_api/*.
Two doors, because an iframe's sub-resources carry no Authorization header:
the ordinary routes go through the platform's gate, and /_web/* is declared
unauthenticated and authenticates itself with a minted, path-scoped cookie —
32 random bytes against the user who asked, not dev-proxy's constant =1 which
anyone knowing the cookie name can set. Verifying it also sets `user`, because
createSidecarProxy fills X-Officer-User from it and the sidecar refuses a
request without one.
Ships an affordance: git for what git does, tea for pull requests and issues.
Nothing copies it into capabilities/ yet — gitea is that mechanism's first
customer.
git + tea: a green glazed teacup with the branch diagram pressed into its face
as a maker's emblem, and a tea-bench scene for the splash.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Empty on purpose. Created so assets/icon.png and assets/splash.png can land
before the plugin does — presence is the declaration, so nothing needs
registering once they are here.
officer