gitea/PLUGIN.md

Gitea — the extraction record

Extracted on 2026-08-19, the eleventh plugin out — and the first that is not a move. plugins/EXTRACTING-A-PLUGIN.md is the runbook for the ordinary case; this was not it.

The old UI was deleted, not moved

Seventeen files under apps/Gitea/ reimplemented a fraction of an interface Gitea already has, and every one of them was a promise to keep pace with a project that moves faster than this plugin will. They were deleted rather than carried across.

That decision removed a platform change nobody has to build now. useGiteaLocation read :owner/:name/:tab/:item from five route patterns; a plugin gets two, so extracting as-is would have required teaching the plugin system to declare extra route patterns. Nothing inside an iframe needs a route, so the requirement evaporated with the screen.

There was no regression window either: gitea's router had been commented out of hono.ts since 2026-08-13 with api: [], and officer-gitea was not running anywhere. The screen rendered and every request 404'd. Nothing working was lost because nothing was working.

Why a proxy, and not simply an iframe

Officer and Gitea are different registrable domains. An iframe pointed straight at gitea.officer.dev gets a login page whose session cookie the browser discards as third-party — a frame that can never stay signed in.

Served through Officer's own origin, the cookie is first-party and survives. X-Frame-Options and Content-Security-Policy are stripped on the way through, which is safe only because the frame is the same origin the browser has already authenticated.

Whose Gitea account you are looking at

Your own. /_web/* forwards the browser's own cookies and injects nothing.

That is the one thing here not to get wrong. The sidecar holds an API token, and injecting it into the web proxy would show every user the OWNER'S view of every repository. The token is used only by /_api/*, for the small things around the frame.

The consequence is that each person signs in to Gitea themselves, once, inside the frame. Gitea's reverse-proxy authentication (ENABLE_REVERSE_PROXY_AUTHENTICATION, the same shape as Radicale's http_x_remote_user) would remove that step, and is deliberately not used: it trusts a header completely, and this instance is network-reachable rather than loopback-only.

Two doors

	gated by	used by
/_config, /_health, /_api/*	the platform's own gate	the panel
/_web/*	a minted, path-scoped cookie	the iframe

An iframe's sub-resources — every stylesheet, script and avatar — are fetched with no Authorization header, so /_web/* is declared in unauthenticatedPaths and authenticates itself.

The cookie holds 32 random bytes held in memory against the user who asked for it, not dev-proxy's constant =1, which anyone who knows the cookie name can set. use() verifies it and sets user on the context — not a convenience: createSidecarProxy reads ctx.get('user').id to fill X-Officer-User, and the sidecar refuses a request without it. On this path the platform's gate never ran, so the cookie is where the account comes from.

What that protects is narrow, and worth stating plainly: Gitea authenticates the person itself, so an unauthenticated caller reaching /_web/ sees a login page. This stops Officer being used as an open proxy to it. A manners problem, cheaply fixed.

The rewriter

Gitea believes it lives at /. Its pages are full of root-absolute links — /user/login, /assets/index.js — and inside the frame those resolve against Officer's origin. The page renders perfectly and falls apart on the first click.

sidecar/rewrite.ts handles four places a URL hides, and they fail differently:

	why it matters
href / src / action attributes	the ordinary case: clicks and assets
window.config.appSubUrl	the highest-value line here — Gitea's own client JS prefixes every URL it builds with this, so filling it in makes Gitea correct itself rather than by interception
Location headers	the most visible failure: Gitea redirects after every login and form post, and an unrewritten one navigates the frame out of the proxy
absolute URLs built from ROOT_URL	the most damaging: they leave for a third-party origin where the session cookie is dropped, so the user is silently signed out

That last one needs to know 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 — appSubUrl removes the need. And clone URLs, which must keep working for whoever copies them.

Cookies get their Path narrowed to the frame so Gitea's session stays out of the platform's API. Secure is left exactly as Gitea set it: adding it breaks a plain-http install, removing it weakens one that meant it.

Eighteen tests cover it, and they are the only part of this plugin that can be verified 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.

The frame is forwarded by hand

/_web/* does NOT go through createSidecarProxy. That forwarder passes exactly three headers — content-type, range, if-none-match — and its restraint is what makes it safe to share between every sidecar. It strips cookies, and this path is nothing but cookies. Loosening it for gitea would loosen it for the wallet, so this one route forwards the request itself. Everything else still uses the shared proxy.

What moved

Was	Is now
src/servers/sidecar/gitea/* (2 files)	sidecar/* — plus the new /_web proxy
src/servers/api/gitea/router.ts	api/router.ts — plus the cookie door
src/workspaces/officerdev/src/apps/Gitea/* (17 files)	deleted
src/apps/officer-web/Screens/Dashboard/Gitea/*	deleted
—	web/GiteaFrame.tsx, one panel

It also stopped being a core dock item. Gitea was hardcoded in CORE_DOCK_ITEMS, the only installable feature that was; its tile now arrives from assets/icon.png like every other plugin's.

Not self-contained

The connection lives in core service_connections, and 'gitea' stays in the platform's ServiceName union — the same coupling transmission, soulseek and the wallet have. Gitea is the reason that union has the "member rows carry only a token and inherit the owner's URL" shape at all.

Affordance

Ships one, in affordances/: use plain git for what git already does, and tea for pull requests, issues and comments. Nothing copies it into capabilities/affordances/ yet — plugin contribution is listed in TODO.md and gitea is its first customer.

tea itself is not provisioned per user yet either. Note the trap for whoever does it: the Debian package named tea is a graphical text editor, not Gitea's CLI, and Bun.which('tea') cannot tell them apart.