@vantran-se/openchamber-web 1.23.0 → 1.24.3

package/server/lib/guests/DOCUMENTATION.md

@@ -0,0 +1,68 @@
+# Guest panels
+
+## Purpose
+
+OpenChamber-owned install and static serve for iframe guests. This is not the OpenCode plugin manager (`plugin-routes.js` / Settings → Plugins).
+
+## Routes
+
+- `POST /api/guests/:id/storage` accepts the SDK's `GuestStorageRequest` and returns `GuestStorageResult`. It requires an installed, enabled, fully approved guest with either a panel or background entry, but no additional capability. The UI host supplies the frame's own identity. Guest-scoped asset tokens cannot call this route. Data lives beside `extensions.json` in `guest-storage/<id>.json`. Each key is 1 to 128 characters, each JSON value at most 64 KiB UTF-8, the whole namespace at most 2 MiB and 2,000 keys. `storage.js` owns serialized authorization/read/write/removal; writes are atomic and failures preserve prior bytes. `uninstallGuest` removes storage for every install source. Missing keys return `found: false`, including after removal; stored JSON null returns `found: true`.
+- `GET /api/guests` also exposes `pageEntry` and optional `pageTitle` for `contributes.page`. Full-screen page HTML and its built scripts pass the same install checks as attach HTML. No new serving/auth path is required.
+
+- `GET /api/guests` returns installed guests. `attach` is `"panel"` or `"dialog"` when declared, and `attachEntry` is the dialog's separate HTML. `version` is the package semver. `integration` is the public slice: name, description, `auth`, and settings; OAuth URLs and tokens stay on the server. `service` includes `runtime`, optional `permissions`, optional `socketBindings`, and `granted`. `capabilities` carries `{ requested, granted }`, derived through the SDK's `requestedGuestCapabilities`. `actions`, `commands`, `tools`, and `filesystem` retain their parsed declarations; UI owns menu placement, command collisions, and tool precedence. `entry` is the optional visible panel and `backgroundEntry` is independent on-demand execution HTML. Background-only extensions get no rail surface; tools-only extensions with neither entry mount no frame. A guest without every requested grant is inactive until approval. `enabled: false` pauses it. A failed listing is 500, never an empty list.
+- `GET /api/guests/:id/oauth/status` — `{ connected, account, hasClient, settings, redirectUri }`. No secrets. Host Linear merges first-party Linear status. `redirectUri` is empty unless `auth` is `oauth`.
+- `PUT /api/guests/:id/oauth/client` — client id and optional secret from the Integrations form. OAuth guests only.
+- `PUT /api/guests/:id/token` — pasted API token. Token guests only. The host probes the declared account path. The token never goes to the iframe.
+- `PUT /api/guests/:id/settings` — declared keys only. The Integrations card calls it when a declared field loses focus with a changed value; there is no Save button. Connect saves the token (and username for `basic`) or the OAuth client id and then the declared fields.
+- `POST /api/guests/:id/oauth/start` — PKCE S256 for OAuth guests. Host Linear starts the first-party Linear authorize URL. Token guests get `NO_INTEGRATION`.
+- `GET /api/guests/:id/oauth/callback` — public HTML page. The provider redirects here with no UI bearer. State and verifier stay on the server. A callback without a matching `state` is refused; nothing is inferred from a pending exchange. Host Linear uses the first-party Linear callback, not this URL.
+- `DELETE /api/guests/:id/oauth` — drops tokens for that guest. Client and settings stay. Host Linear disconnects the first-party Linear workspace.
+- `POST /api/guests/:id/request` — authenticated UI session. Attaches Authorization. Path must stay on that guest's `apiOrigin`. Token guests send the pasted token as is, `Bearer <token>` when the manifest sets `token.scheme: "bearer"`, or `Basic <pair>` for `"basic"`, where `PUT /api/guests/:id/token` took `{ token, username }` and stored `base64(username:token)` as the access token (`USERNAME_MISSING` without a username). Host Linear sends the Linear bearer to `https://api.linear.app` only. Linear issue file URLs stay on `GET /api/linear/issues/get`. The guest proxy does not add Linear headers. A paused extension (`enabled: false`) is 400 `DISABLED`; tokens stay. A guest without the `network` capability granted is 400 `NOT_GRANTED`.
+- `POST /api/guests/:id/service/request` — authenticated UI session. Proxies to that guest's host-spawned service on `127.0.0.1`. Spawns on first use after the grant; every service needs one. Missing grant, missing service, or bad path is 400 with `NO_SERVICE` / `BAD_PATH`. Paused extension is 400 `DISABLED` (service stopped). Ready failure is 502 `SERVICE_FAILED`.
+- `POST /api/guests/:id/files` — authenticated UI session. `{ op: 'read' | 'write' | 'list' | 'stat', path, content? }` (`content` required for `write`, at most `GUEST_FILE_CONTENT_MAX` characters; `path` at most `GUEST_FILE_PATH_MAX`). The open project comes from `resolveOptionalProjectDirectory(req)` (`x-opencode-directory` header or `directory` query). `files.js` resolves the path: relative → joined to the project's realpath, and the deepest existing ancestor is realpath'd so a symlink out of the project is `BAD_PATH`; a relative path with no project is `NO_DIRECTORY`. `/…` or `~/…` → home expanded, normalized, canonicalized the same way, then matched against the package's `contributes.filesystem` globs whose literal prefixes were canonicalized too (`/tmp` → `/private/tmp` on macOS); no match is `BAD_PATH`. Any `..` segment, NUL, or backslash is `BAD_PATH`. Then the grant: project scope needs `files`, outside needs `filesystem`, else `NOT_GRANTED`. Then the operation: read is UTF-8 and refuses a file over the cap with `FILE_TOO_LARGE`; write makes parent directories and lands through a temp file plus rename (a reader never sees a truncated file); list returns `{ name, kind }` sorted by name and capped at `GUEST_FILE_LIST_MAX`, with symlinks as `other`; stat answers `kind: 'missing'` for nothing there. Answers are `{ ok: true, result }`, or `{ error: code, message }` with 400 (404 for `NOT_FOUND`). Paused extension is 400 `DISABLED`. `ENOENT` is `NOT_FOUND`, `EACCES` / `EPERM` is `DENIED`, `EISDIR` / `ENOTDIR` is `BAD_PATH`. Neither the path nor the content is ever logged.
+- `POST /api/guests/:id/generate` — authenticated UI session. `{ prompt, system?, maxOutputTokens? }` (prompt at most `GUEST_GENERATE_PROMPT_MAX`, system `GUEST_GENERATE_SYSTEM_MAX`, tokens `GUEST_GENERATE_OUTPUT_TOKENS_MAX`). Paused extension is 400 `DISABLED`; missing `model` grant is 400 `NOT_GRANTED`. The call goes to `generateSmallModelText` in `lib/small-model`, which resolves and authenticates the Small Model the same way session titles and notes do (settings override → OpenCode config → signed-in provider); the optional `x-opencode-directory` header only picks which OpenCode config is read. No model (404) or Claude Code as the only candidate (422) is 400 `NO_MODEL`; a provider failure is 502 `MODEL_FAILED`. Answer is `{ ok: true, result: { text } }` capped at `GUEST_GENERATE_TEXT_MAX`. Prompt and answer are never logged.
+- `GET /api/guests/:id/service/status` — `{ status }` for that guest's service runtime (`stopped` / `starting` / `ready` / `failed`).
+- `PUT /api/guests/:id/capabilities` — `{ granted: GuestCapability[] }`. The list must equal the package's requested list, or be empty to withdraw approval (which also stops a running service). Anything else is 400 `invalid-request`. `service.granted` mirrors whether `service` is in the granted list. Approval also records the grant's scope (`grant-scope.js` `guestGrantScope`: the sorted `filesystem` patterns, the integration's `apiOrigin` and OAuth `authorizeUrl` / `tokenUrl`, the service's exec names and socket ids) as `capabilityScopes[id]`. When the recorded origin or OAuth endpoints differ from the new ones (`sameCredentialTarget`) the guest's stored tokens are dropped: a token pasted for one API, or a refresh token and client secret minted for one token endpoint, must not follow the integration to another.
+- `PUT /api/guests/:id/service/sockets` — `{ id, path }` for a declared socket binding. Empty or null `path` clears the override. Stops a running service for that guest. Catalog `service.socketBindings` shows `resolved` and `override` for this host.
+- `PUT /api/guests/:id/enabled` — `{ enabled }`. False is a full pause: catalog `enabled: false`, rail/attach/Integrations hide the guest, open panels close, cloud `request` and `service/request` return `DISABLED`, and a running service stops. Tokens and grants stay until Remove.
+- `POST /api/guests` accepts exactly one of `{ path }` or `{ url }`, optional `replace`, and optional `gitIdentityId` for Git installs. `path` is an absolute folder or local ZIP. `url` is HTTPS Git/ZIP, `ssh://` Git, or scp-style SSH. Folder installs persist their realpath; Git and ZIP installs copy into `{openchamberDataDir}/extensions/{id}`. Success is 201, or 200 after replacement. Invalid input is `invalid-path`/`invalid-url`; clone and extraction failures are `clone-failed`/`extract-failed`. A missing selected identity fails cloning rather than falling back to global auth. Missing built scripts are `missing-build`, invalid package/version is `invalid-manifest`, and a newer required host is `host-too-old`. Duplicate installs are 409 `id-taken`/`already-installed`. Other install failures are 400. Clone uses the host's resolved Git binary; orphaned copy folders from interrupted installs can be replaced on retry. Each OpenChamber data directory owns its own catalog.
+- `POST /api/guests/upload` — the archive itself as the body, `Content-Type: application/octet-stream`, for a browser or a remote instance that cannot name a path on the host. Query `replace=true` mirrors the JSON route's `replace`; `name` (the original filename) is accepted and unused, never logged. A wrong content type is 415 `unsupported-media-type`. A `Content-Length` over the cap is refused with 413 `too-large` before the body is read, and a body that grows past the cap without a declared length stops with the same answer. The cap is `OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES`, default 50 MB (`upload.js` `guestUploadMaxBytes`). The bytes go to `installGuestFromZipBuffer`, the same function a local `.zip` path and an https `.zip` URL end in, so results and errors are those of `POST /api/guests` with a zip: 201 / 200 after replace with `{ guest }` (`source: "zip"`), 409 `already-installed` / `id-taken` with `id`, 400 `invalid-manifest`, `missing-build`, `host-too-old`, `extract-failed`. Registered before the `:id` routes because `upload` is a valid panel id shape. Archive contents are never logged.
+- `POST /api/guests/updates/check` — `{ force?: boolean }` → `{ updates: Record<guestId, { version }> }` for every git install whose origin now carries a newer `package.json` `version`. The check runs `git fetch --depth 1 origin <ref|HEAD>` inside the installed clone and reads `FETCH_HEAD:package.json` through the SDK manifest parser; the only signal is semver (`updates.js` `compareSemver`, prerelease below release), no commit hashes. Results sit in a memory cache per store file and guest id for `UPDATE_CHECK_TTL_MS` (one hour); `force` asks the network again. That cache is separate from the catalog cache, so a store write does not drop it. One guest's failed fetch never hides another's update. Folder and zip installs are never checked.
+- `POST /api/guests/:id/update` — replace the installed git copy with a fresh clone of its stored origin. Answers `{ guest }` (the refreshed catalog row) or 400 `{ error }` with `not-git` (folder, zip, or no stored origin), `clone-failed`, `invalid-manifest` (also when the clone declares a different panel id), `missing-build`, `host-too-old` (body may include `required`), or `swap-failed`. Unknown id is 404. Grants, tokens, settings, and the paused flag are keyed by guest id and stay as they were; a version that asks for more capabilities shows up as needs-approval in the catalog and goes through the usual review dialog.
+- `DELETE /api/guests/:id` — drops the store row, any service grant, and socket overrides; stops a running service. Path-install does not delete the user's folder. Zip and git copies under `{openchamberDataDir}/extensions/` are deleted. Unknown id is 404.
+- `GET /api/guests/:id/{*filePath}` serves package-local files. Unknown IDs, escapes, missing files, and unknown types return 404. HTML and JS require either `entry` or `backgroundEntry`, expressed by `resolveGuestServedFile`'s `hasRuntime` option. Tools-only extensions still serve their SVG icons but no executable content. Guest HTML propagates the scoped `oc_url_token` onto relative script/link/image URLs. The token is minted for `guest:<id>` and works only under that guest's asset route, never `/api/fs/raw` or event streams. Every response carries `Content-Security-Policy: sandbox allow-scripts`, including direct document navigation. The host serves built files from disk and never compiles guest sources.
+
+## Install
+
+`contributes.background.entry` is optional package-local `.html`, separate from `panel.entry`. Install validates its HTML and every referenced built script using the same path confinement as visible panels. `backgroundEntry` is exposed on the catalog independently of `entry`; adding it does not create a rail icon or a visible page. Capabilities, services, integrations, and storage work with either execution entry. The SDK refuses visible contributions without `panel.entry` and all runtime contributions when neither entry exists. See `packages/sdk/DOCUMENTATION.md` for on-demand invocation ownership.
+
+`html-styles.js` appends the SDK's shared scrollbar stylesheet to served HTML, including requests without an asset token. This applies to existing panel, page, and attach bundles in direct and relay mode; the relay loader retains the inline style in `srcDoc`. Appending preserves the doctype and avoids rewriting tag-like text inside scripts or comments. Authored CSP stays intact and can block inline styling. Package files on disk and non-HTML responses are unchanged. Scrollbar colors follow the SDK theme variables inside the frame.
+
+Built-ins ship with the app; user extensions are installed separately. Add a folder, local ZIP, HTTPS Git/ZIP URL, or SSH Git address from Settings → Extensions. The ZIP picker and drop zone upload the archive on web and remote desktop instances. A guest with a page must ship built classic-IIFE JavaScript, for example from `bunx openchamber-guest-bundle panel/main.ts panel/main.js`; the sandbox does not support ESM imports. `package.json` needs a semver version. A missing panel SVG or invalid manifest fails installation; page-less tools-only packages skip HTML/script checks. Optional `engines.openchamber` is checked against this host. Provider accounts are connected separately in Settings → Integrations.
+
+Folder installs store their realpath with `source: "path"`. ZIP and Git copies live in `{openchamberDataDir}/extensions/{id}`. Git URLs may end in `#branch-or-tag`; clones use `--branch <ref> --depth 1`. `gitOrigins` stores `{ url, ref?, gitIdentityId? }` per install path and is removed on uninstall. Legacy origins without an identity retain global authentication. Malformed origins are dropped individually. The public catalog exposes the origin URL/ref, never the key path. Named profiles are re-resolved on each clone or update fetch so key rotation applies; missing profiles fail closed. Global auth preserves the server's SSH agent and Git/SSH configuration. ZIP limits remain 20MB for path/URL installs, 500 files and 40MB expanded, store/deflate only, no encryption, zip64 or parent-path escapes. Uninstall deletes copies and leaves folder-install sources intact.
+
+OAuth and pasted tokens live in `{openchamberDataDir}/guest-auth.json`, each entry with the `target` it was minted for (`apiOrigin`, and for OAuth `authorizeUrl` and `tokenUrl`). `takeUsableGuestAuth` runs before every use (proxy, refresh, the status card): tokens whose target differs from what the package declares now, or that carry no target, are dropped on the spot, whatever the grants say. A pending authorization carries the same target; the callback refuses the exchange (`TARGET_CHANGED`) when the package changed its endpoints in between, and the exchange itself goes to the pending target's `tokenUrl`, never to the current manifest's. The client id and secret carry their own `clientTarget`, written by `PUT /api/guests/:id/oauth/client` (`saveGuestOAuthClient`: an empty secret field keeps the stored secret only for the same client id and the same endpoints, decided under the store lock; a new id or moved endpoints drop it); `usableClientCredentials` treats a client entered for other endpoints as absent (`CLIENT_MISSING` on Connect, `hasClient: false` on the card), so a moved package gets no old secret and the user enters new credentials. Every token write that follows a network round trip (the code exchange, a refresh) goes through `patchGuestAuth` with an `expect` predicate checked under the store lock: the entry must still hold the tokens and target the round trip started from, else the answer is dropped and the entry left as it is. The proxy's cleanup after a 401 is scoped the same way: `dropGuestTokens` with an `expect` on the access token the request was refused with, so a refresh that came back empty because the user reconnected meanwhile never erases the new connection. Host Linear tokens stay in `linear-auth.json`. Writes are atomic and `0o600`. The file is per OpenChamber instance, same as `extensions.json`. Web and desktop share it. VS Code and mobile set the guest catalog to `unsupported`. That is not an empty ready list. Those cards stay hidden.
+
+A missing folder is omitted from the list. Other guests stay. A corrupt `extensions.json` is 500, not an empty catalog. A missing or blank `guest-auth.json` is an empty store. Corrupt JSON there is 500, not a disconnected card. This is not Settings → Plugins.
+
+## Invariants
+
+- Built-in packages come from the app-owned registry bound by `registerBuiltInGuests` at server startup. Source/build/packaging rules are in `packages/extensions/DOCUMENTATION.md`. They receive only their declared grants automatically; ordinary runtime and enabled checks still apply. `openchamber-builtin-` IDs are reserved from user installs, including replacement. DELETE, Git update and grant-edit routes refuse built-ins. Disable preserves account/storage data and stops their services.
+
+- Grants are narrowed on read, never trusted as stored. `listInstalledGuestsUncached` passes each guest's stored list through `effectiveGrants(granted, storedScope, currentScope)`: `filesystem`, `network`, and `service` only count while the scope recorded at approval equals what the package declares now, and never count without a recorded scope. A newer version that widens its patterns, moves its API origin, or asks for more exec names or sockets shows up as needs-approval and is refused by every proxy meanwhile. Routes and `proxyGuestServiceRequest` take the grant list from the catalog row (`guest.capabilityGrants`), not from the store.
+- Store changes are read-modify-write under one lock per file (`updateExtensionStore`): Allow, Pause, a socket override, an install, and an uninstall landing at the same time all keep each other's result. `guest-auth.json` has the same lock (`withAuthStoreLock`) and every temp file name is unique.
+- ZIP downloads validate and pin each HTTPS hop, at most five. Git clones and update fetches share `prepareGuestGitNetwork`. HTTPS retains `http.followRedirects=false` and `http.curloptResolve` pinning. SSH validates the username/host/path, rejects password-bearing URLs and private DNS answers, pins `Hostname` to a resolved public address, and retains the original host for host-key checks through `HostKeyAlias`. Default SSH options use batch mode and `StrictHostKeyChecking=accept-new`, with ProxyCommand/ProxyJump disabled. Identity key paths are shell-quoted; keys and SSH agent sockets stay on the server. Public Git hosts are supported, not local SSH aliases or private-network targets. Existing user-configured Git/SSH commands remain trusted server configuration.
+- The catalog cache is version-guarded: `invalidateGuestCatalog` bumps a per-path version, the store notifies before and after each write, and a listing only caches its result when the version did not move while it read. A read that straddled a withdrawal therefore never serves the old grants for the TTL.
+- Stopping a service also cancels a request in flight: `stopGuestService` (Pause, Remove, withdrawn approval, socket change, host quit) bumps a per-guest epoch. `proxyGuestServiceRequest` reads the epoch before its first store read, hands it to the start, and checks it again after the service is up; `startGuestService` checks it after every await, right before `spawn`, and while polling readiness. Pause anywhere between the request's enabled check and the proxied call ends with no process and `NO_SERVICE`. Internal cleanup of a dead or failed runtime before a restart is `discardRuntime`, which does not bump the epoch: a crash is not a Pause, so the request that triggers the restart goes through.
+
+- Paths stay inside the package root (`realpath`). `..`, absolute paths, and URLs do not serve.
+- Only an allowlisted content type is served.
+- Host and guest speak `@openchamber/sdk`. Do not copy those types into `packages/ui`.
+- `contributes.actions`, `contributes.commands`, and `contributes.tools` are validated by the SDK parse at install (`invalid-actions` / `invalid-commands` / `invalid-tools` surface as `invalid-manifest`) and copied to the catalog row unchanged. Tool presentations are applied in the UI only (`packages/ui/src/lib/guests/tool-presentation.ts`); no server route reads them. No server route runs an action or a command: the message or session item is built in the UI from the same records Export as Markdown uses, and a slash command is answered by the guest frame over `postMessage`. The rail badge is UI memory only.
+- `contributes.attach` is copied as `"panel"` or `"dialog"`. The composer + menu and New Worktree read that field. Omitted guests stay off those menus. The object form's `entry` (dialog only) is checked at install like `panel.entry`: missing HTML is `invalid-manifest`, an unbuilt script it loads is `missing-build`; the catalog exposes it as `attachEntry` and the attach window loads that page instead of `panel.entry`. The optional attach `data` payload lives only in the UI's chip, queued context part, and session metadata snapshot; no server route parses it.
+- `request` never leaves the declared `apiOrigin`. A 401 refreshes once. If that fails, tokens for that guest are dropped. Host Linear does not drop Linear auth on a failed GraphQL query. A paused guest never proxies `request` or `serviceRequest`.
+- `serviceRequest` never leaves that guest's loopback port. Auth to the service is `Authorization: Bearer` with a host-minted token. The service env is an allowlist (PATH, HOME, temp, locale, Windows system variables) plus `OPENCHAMBER_SERVICE_*`; host secrets are not inherited. There is no sandbox: an allowed service has the user's full access, and the grant card says so. Ready is `GET /health` → 200. Parallel first requests share one spawn; they must not kill each other mid-start. Host quit stops every service. Disabling a guest stops its service without clearing OAuth or grants.
+- File access is decided in `files.js` on canonical paths, never on the string the guest sent. `matchesFilesystemPattern`, `expandHome`, and `globToRegExp` are pure; `resolveGuestFilePath` and `runGuestFileOperation` take `fsPromises` / `nodePath` so tests can stub the OS. The project directory is whatever `resolveOptionalProjectDirectory` validated for this request, so a guest cannot name a project the UI did not open.
+- Update swap (`updates.js` `updateGuest`): the new clone lands in `{dataDir}/extensions/.tmp-<id>-<random>` and is inspected exactly like an install before anything else moves. Only then: stop the guest's service, rename current → `.old-<id>`, rename temp → final, delete `.old-<id>`. Any failure before the swap deletes the temp dir and leaves the install untouched; a failed second rename moves `.old-<id>` back. The store row is not rewritten (same path, same id), the catalog cache and that guest's update cache entry are dropped.
+- The OAuth callback skips UI auth. Everything else under `/api/guests` stays behind the usual session.

package/server/lib/guests/auth-store.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+
+const PANEL_ID = /^[a-z][a-z0-9-]*$/;
+const SETTING_KEY = /^[a-z][a-z0-9-]*$/;
+
+const guestAuthEntrySchema = z.object({
+  clientId: z.string().min(1).optional(),
+  clientSecret: z.string().min(1).optional(),
+  accessToken: z.string().min(1).optional(),
+  refreshToken: z.string().min(1).nullable().optional(),
+  tokenType: z.string().min(1).optional(),
+  expiresAt: z.number().int().positive().nullable().optional(),
+  account: z.string().max(200).optional(),
+  settings: z.record(z.string().regex(SETTING_KEY), z.string().max(2000)).optional(),
+  authorizedAt: z.number().int().positive().optional(),
+  // Where the tokens were minted for. Checked before every use, so a
+  // package that moved its API origin or OAuth endpoints cannot receive
+  // credentials the user connected for the old ones.
+  target: z.object({
+    apiOrigin: z.string().min(1),
+    authorizeUrl: z.string().min(1).optional(),
+    tokenUrl: z.string().min(1).optional(),
+  }).optional(),
+  // Where the client id and secret were entered for. A package that moved
+  // its endpoints gets no client credentials until the user enters them
+  // again; they are never carried over.
+  clientTarget: z.object({
+    apiOrigin: z.string().min(1),
+    authorizeUrl: z.string().min(1).optional(),
+    tokenUrl: z.string().min(1).optional(),
+  }).optional(),
+});
+
+const storeSchema = z.object({
+  guests: z.record(z.string().regex(PANEL_ID), guestAuthEntrySchema),
+});
+
+const dataDirSchema = z.string().min(1).refine((entry) => !entry.includes('\0') && path.isAbsolute(entry));
+
+export const guestAuthPersistPath = (dataDir) => {
+  const parsed = dataDirSchema.safeParse(dataDir);
+  if (!parsed.success) {
+    throw new Error('Guest auth needs an absolute OpenChamber data dir');
+  }
+  return path.join(parsed.data, 'guest-auth.json');
+};
+
+const parseStore = (raw) => {
+  try {
+    const parsed = storeSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+};
+
+export const readGuestAuthStore = async (persistPath) => {
+  try {
+    const raw = await fs.readFile(persistPath, 'utf8');
+    const text = raw.replace(/^\uFEFF/, '').trim();
+    if (text === '') {
+      return { guests: {} };
+    }
+    const parsed = parseStore(text);
+    if (!parsed) {
+      throw new Error('Invalid guest auth store');
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return { guests: {} };
+    }
+    throw error;
+  }
+};
+
+/** @type {Map<string, Promise<unknown>>} */
+const writeChains = new Map();
+let writeSequence = 0;
+
+// Two writers at once (a token refresh while a settings field saves) used to
+// share one temp file and a stale read: one of them lost. Every change to one
+// store file now runs read → change → write as a single step, one after
+// another, each on its own temp file.
+const withAuthStoreLock = (persistPath, run) => {
+  const previous = writeChains.get(persistPath) ?? Promise.resolve();
+  const next = previous.catch(() => undefined).then(run);
+  const chained = next.finally(() => {
+    if (writeChains.get(persistPath) === chained) writeChains.delete(persistPath);
+  });
+  writeChains.set(persistPath, chained);
+  return next;
+};
+
+const writeGuestAuthStoreUnlocked = async (store, persistPath) => {
+  const parsed = storeSchema.safeParse(store);
+  if (!parsed.success) {
+    throw new Error('Invalid guest auth store');
+  }
+  await fs.mkdir(path.dirname(persistPath), { recursive: true });
+  const tmp = `${persistPath}.tmp-${process.pid}-${Date.now()}-${(writeSequence += 1)}`;
+  await fs.writeFile(tmp, `${JSON.stringify(parsed.data, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  await fs.rename(tmp, persistPath);
+  await fs.chmod(persistPath, 0o600);
+};
+
+
+export const getGuestAuth = async (guestId, persistPath) => {
+  const store = await readGuestAuthStore(persistPath);
+  return store.guests[guestId] ?? null;
+};
+
+/**
+ * Apply `patch` to one guest's entry, read and written under the store lock.
+ * With `expect`, the patch only lands when the entry read under the lock
+ * satisfies it; a caller that spent a network round trip on the old entry
+ * (a token refresh) uses this to drop its result when the entry moved on.
+ * `patch` may be a function of the entry read under the lock, for a change
+ * that depends on what is there (a client id replacing another one).
+ * Returns the entry as stored afterwards, or `null` when it is gone.
+ */
+export const patchGuestAuth = (guestId, patch, persistPath, expect = null) => withAuthStoreLock(persistPath, async () => {
+  const store = await readGuestAuthStore(persistPath);
+  const current = store.guests[guestId] ?? null;
+  if (expect && !expect(current)) {
+    return current;
+  }
+  const next = { ...(current ?? {}) };
+  const resolvedPatch = typeof patch === 'function' ? patch(current) : patch;
+  for (const [key, value] of Object.entries(resolvedPatch)) {
+    if (value === undefined) {
+      delete next[key];
+    } else {
+      next[key] = value;
+    }
+  }
+  const guests = { ...store.guests };
+  const empty = !next.clientId
+    && !next.clientSecret
+    && !next.accessToken
+    && !next.refreshToken
+    && (!next.settings || Object.keys(next.settings).length === 0);
+  if (empty) {
+    delete guests[guestId];
+  } else {
+    guests[guestId] = next;
+  }
+  await writeGuestAuthStoreUnlocked({ guests }, persistPath);
+  return guests[guestId] ?? null;
+});
+
+/**
+ * Forget the tokens. With `expect`, only when the entry read under the lock
+ * still holds the tokens the caller is reacting to; a caller that saw a 401
+ * on one access token must not erase a newer connection made meanwhile.
+ */
+export const dropGuestTokens = async (guestId, persistPath, expect = null) => {
+  const current = await getGuestAuth(guestId, persistPath);
+  if (!current) {
+    return null;
+  }
+  return patchGuestAuth(guestId, {
+    accessToken: undefined,
+    refreshToken: undefined,
+    target: undefined,
+    tokenType: undefined,
+    expiresAt: undefined,
+    account: undefined,
+    authorizedAt: undefined,
+  }, persistPath, expect);
+};
+
+/** Drop everything stored for a guest: tokens, client credentials, and settings. Used when the package is removed. */
+export const forgetGuestAuth = (guestId, persistPath) => withAuthStoreLock(persistPath, async () => {
+  const store = await readGuestAuthStore(persistPath);
+  if (!(guestId in store.guests)) {
+    return;
+  }
+  const guests = { ...store.guests };
+  delete guests[guestId];
+  await writeGuestAuthStoreUnlocked({ ...store, guests }, persistPath);
+});

package/server/lib/guests/auth-store.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  dropGuestTokens,
+  forgetGuestAuth,
+  getGuestAuth,
+  guestAuthPersistPath,
+  patchGuestAuth,
+  readGuestAuthStore,
+} from './auth-store.js';
+
+describe('guestAuthPersistPath', () => {
+  test('joins the instance data dir and refuses a relative path', () => {
+    const dataDir = path.join(os.tmpdir(), 'oc-guest-auth-a');
+    expect(guestAuthPersistPath(dataDir)).toBe(path.join(dataDir, 'guest-auth.json'));
+    expect(() => guestAuthPersistPath('relative')).toThrow('absolute OpenChamber data dir');
+  });
+});
+
+describe('guest auth store', () => {
+  test('round-trips tokens and writes 0o600', async () => {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'oc-guest-auth-'));
+    const file = guestAuthPersistPath(dir);
+    expect(await readGuestAuthStore(file)).toEqual({ guests: {} });
+    await patchGuestAuth('clickup', {
+      clientId: 'id',
+      clientSecret: 'secret',
+      accessToken: 'tok',
+      account: 'ada',
+      settings: { 'list-id': '123' },
+    }, file);
+    expect(await getGuestAuth('clickup', file)).toMatchObject({
+      clientId: 'id',
+      accessToken: 'tok',
+      account: 'ada',
+      settings: { 'list-id': '123' },
+    });
+    expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    await dropGuestTokens('clickup', file);
+    const after = await getGuestAuth('clickup', file);
+    expect(after?.accessToken).toBeUndefined();
+    expect(after?.clientId).toBe('id');
+    expect(after?.settings).toEqual({ 'list-id': '123' });
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  });
+
+  test('forgets a guest entirely when its package is removed', async () => {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'oc-guest-auth-'));
+    const file = guestAuthPersistPath(dir);
+    try {
+      await patchGuestAuth('clickup', { clientId: 'app', clientSecret: 'secret', accessToken: 'token' }, file);
+      await patchGuestAuth('other', { accessToken: 'keep' }, file);
+      await forgetGuestAuth('clickup', file);
+      expect(await getGuestAuth('clickup', file)).toBeNull();
+      expect((await getGuestAuth('other', file))?.accessToken).toBe('keep');
+    } finally {
+      await fs.promises.rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('treats a blank file as an empty store', async () => {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'oc-guest-auth-'));
+    const file = guestAuthPersistPath(dir);
+    await fs.promises.writeFile(file, '', 'utf8');
+    expect(await readGuestAuthStore(file)).toEqual({ guests: {} });
+    await fs.promises.writeFile(file, '\uFEFF\n', 'utf8');
+    expect(await readGuestAuthStore(file)).toEqual({ guests: {} });
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  });
+
+  test('refuses a corrupt store', async () => {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'oc-guest-auth-'));
+    const file = guestAuthPersistPath(dir);
+    await fs.promises.writeFile(file, '{"guests":[]}', 'utf8');
+    try {
+      await readGuestAuthStore(file);
+      throw new Error('should have thrown');
+    } catch (error) {
+      expect(String(error)).toContain('Invalid guest auth store');
+    }
+    await fs.promises.writeFile(file, '{', 'utf8');
+    try {
+      await readGuestAuthStore(file);
+      throw new Error('should have thrown');
+    } catch (error) {
+      expect(String(error)).toContain('Invalid guest auth store');
+    }
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('concurrent auth changes', () => {
+  test('two patches at once both land', async () => {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'oc-guest-auth-'));
+    const file = guestAuthPersistPath(dir);
+    try {
+      await Promise.all([
+        patchGuestAuth('alpha', { accessToken: 'tok-a' }, file),
+        patchGuestAuth('beta', { accessToken: 'tok-b' }, file),
+        patchGuestAuth('alpha', { settings: { 'list-id': '7' } }, file),
+      ]);
+      expect(await getGuestAuth('alpha', file)).toMatchObject({ accessToken: 'tok-a', settings: { 'list-id': '7' } });
+      expect(await getGuestAuth('beta', file)).toMatchObject({ accessToken: 'tok-b' });
+      expect(fs.readdirSync(dir).filter((name) => name.includes('.tmp-'))).toEqual([]);
+    } finally {
+      await fs.promises.rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/server/lib/guests/background.test.js

@@ -0,0 +1,83 @@
+import { afterEach, expect, test } from 'bun:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import request from 'supertest';
+import { inspectGuestPackage, toPublicGuest } from './catalog.js';
+import { registerGuestRoutes } from './routes.js';
+
+const roots = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
+const fixture = async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-background-')); roots.push(root);
+  const packageRoot = path.join(root, 'package');
+  await fs.mkdir(packageRoot);
+  await fs.writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({ name: 'background-test', version: '1.0.0', openchamber: {
+    apiVersion: 1, contributes: {
+      panel: { id: 'background-test', name: 'Background Test', icon: 'apps' },
+      background: { entry: 'index.html' },
+      capabilities: ['files'], commands: [{ name: 'test-background' }],
+      actions: [{ id: 'count', label: 'Count', where: 'message', mode: 'background' }],
+    },
+  } }));
+  return { root, packageRoot };
+};
+
+test('background-only packages validate HTML and built scripts and expose a separate catalog entry', async () => {
+  const { packageRoot } = await fixture();
+  expect(await inspectGuestPackage(packageRoot)).toMatchObject({ ok: false, code: 'invalid-manifest' });
+  await fs.writeFile(path.join(packageRoot, 'index.html'), '<script src="main.js"></script>');
+  await fs.writeFile(path.join(packageRoot, 'main.ts'), 'export {};');
+  expect(await inspectGuestPackage(packageRoot)).toMatchObject({ ok: false, code: 'missing-build' });
+  await fs.writeFile(path.join(packageRoot, 'main.js'), 'void 0;');
+  const result = await inspectGuestPackage(packageRoot);
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw new Error(result.code);
+  const row = toPublicGuest(result.guest);
+  expect(row.entry).toBeUndefined();
+  expect(row.backgroundEntry).toBe('index.html');
+  expect(row.attach).toBeUndefined();
+  expect(row.actions).toHaveLength(1);
+  expect(row.commands).toHaveLength(1);
+  expect(row.capabilities).toEqual({ requested: ['files'], granted: [] });
+});
+
+test('background entry and its scripts cannot escape the installed package through symlinks', async () => {
+  const { root, packageRoot } = await fixture();
+  const outside = path.join(root, 'outside.html');
+  await fs.writeFile(outside, '<p>Outside</p>');
+  await fs.symlink(outside, path.join(packageRoot, 'index.html'));
+  expect(await inspectGuestPackage(packageRoot)).toMatchObject({ ok: false, code: 'invalid-manifest' });
+  await fs.unlink(path.join(packageRoot, 'index.html'));
+  await fs.writeFile(path.join(packageRoot, 'index.html'), '<script src="main.js"></script>');
+  await fs.writeFile(path.join(root, 'outside.js'), 'void 0;');
+  await fs.symlink(path.join(root, 'outside.js'), path.join(packageRoot, 'main.js'));
+  expect(await inspectGuestPackage(packageRoot)).toMatchObject({ ok: false, code: 'missing-build' });
+});
+
+test('background install serves sandboxed assets and storage obeys approval and enabled state', async () => {
+  const { root, packageRoot } = await fixture();
+  await fs.writeFile(path.join(packageRoot, 'index.html'), '<script src="main.js"></script>');
+  await fs.writeFile(path.join(packageRoot, 'main.js'), 'void 0;');
+  const app = express(); registerGuestRoutes(app, { openchamberDataDir: root, resolveGitBinaryForSpawn: () => 'git' });
+  const installed = await request(app).post('/api/guests').send({ path: packageRoot }).expect(201);
+  expect(installed.body.guest.backgroundEntry).toBe('index.html');
+  expect(installed.body.guest.entry).toBeUndefined();
+  const catalog = await request(app).get('/api/guests').expect(200);
+  expect(catalog.body.guests[0].backgroundEntry).toBe('index.html');
+  const html = await request(app).get('/api/guests/background-test/index.html?oc_url_token=test-scope').expect(200);
+  expect(html.headers['content-security-policy']).toBe('sandbox allow-scripts');
+  expect(html.text).toContain('main.js?oc_url_token=test-scope');
+  expect((await request(app).get('/api/guests/background-test/main.js').expect(200)).text).toBe('void 0;');
+  await request(app).post('/api/guests/background-test/storage').send({ op: 'set', key: 'count', value: 1 }).expect(400);
+  await request(app).put('/api/guests/background-test/capabilities').send({ granted: ['files'] }).expect(200);
+  await request(app).post('/api/guests/background-test/storage').send({ op: 'set', key: 'count', value: 1 }).expect(200);
+  expect((await request(app).post('/api/guests/background-test/storage').send({ op: 'get', key: 'count' }).expect(200)).body).toMatchObject({ found: true, value: 1 });
+  await request(app).put('/api/guests/background-test/enabled').send({ enabled: false }).expect(200);
+  await request(app).post('/api/guests/background-test/storage').send({ op: 'set', key: 'count', value: 2 }).expect(400);
+  await request(app).put('/api/guests/background-test/enabled').send({ enabled: true }).expect(200);
+  expect((await request(app).post('/api/guests/background-test/storage').send({ op: 'get', key: 'count' }).expect(200)).body).toMatchObject({ value: 1 });
+  await request(app).put('/api/guests/background-test/capabilities').send({ granted: [] }).expect(200);
+  await request(app).post('/api/guests/background-test/storage').send({ op: 'get', key: 'count' }).expect(400);
+});

package/server/lib/guests/builtins.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+
+const BUILTIN_PREFIX = 'openchamber-builtin-';
+export const DEFAULT_BUILTIN_ROOT = fileURLToPath(new URL('../../built-in-extensions/', import.meta.url));
+export const builtInExtensionSchema = z.object({
+  id: z.string().regex(/^openchamber-builtin-[a-z][a-z0-9-]*$/),
+  directory: z.string().regex(/^[a-z][a-z0-9-]*$/),
+});
+export const builtInRegistrySchema = z.object({
+  version: z.literal(1),
+  extensions: z.array(builtInExtensionSchema),
+}).superRefine(({ extensions }, context) => {
+  const ids = new Set();
+  const directories = new Set();
+  for (const entry of extensions) {
+    if (ids.has(entry.id) || directories.has(entry.directory)) {
+      context.addIssue({ code: 'custom', message: 'Built-in extension IDs and directories must be unique' });
+    }
+    ids.add(entry.id);
+    directories.add(entry.directory);
+  }
+});
+
+export const isReservedBuiltInId = (id) => id.startsWith(BUILTIN_PREFIX);
+
+/** Only application startup supplies this root; manifests and HTTP input cannot select it. */
+export const readBuiltInRegistry = async (root = DEFAULT_BUILTIN_ROOT) => {
+  const realRoot = await fs.realpath(root);
+  const registry = builtInRegistrySchema.parse(JSON.parse(await fs.readFile(path.join(realRoot, 'registry.json'), 'utf8')));
+  return { root: realRoot, extensions: registry.extensions };
+};