@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/tools/extensions.js

@@ -5,10 +5,12 @@ import { resolvePathLikePython } from '../workspace/paths.js';
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { atomicWriteText } from '../fs/atomic.js';
+import { InvalidDocument } from '../sessions/storage/backend.js';
+import { readDocument } from '../sessions/storage/document.js';
 import { readZip } from '../workspace/unzip.js';
 import { isDict } from '../config/agent-config.js';
 import { str } from '../util.js';
+import { SKIN_TOKEN_NAMES, SKIN_VALUE_RE } from '@maudecode/talaria-web-contracts';
 export class ExtensionError extends Error {
     status;
     constructor(message, status = 400) {
@@ -34,6 +36,9 @@ const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
 const ALLOWED_ASSET_PREFIXES = ['/extensions/', '/static/'];
 const ALLOWED_DOTFILES = new Set(['.gitkeep', '.gitignore', '.gitattributes', '.env.example']);
 export const EXTENSION_MIME = { css: 'text/css', js: 'application/javascript', html: 'text/html', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', ico: 'image/x-icon', gif: 'image/gif', webp: 'image/webp', woff: 'font/woff', woff2: 'font/woff2', ttf: 'font/ttf', otf: 'font/otf', wasm: 'application/wasm' };
+const SKIN_TOKENS = new Set(SKIN_TOKEN_NAMES);
+/** Skin keys and TTS engine ids share the frontend contract's slug. */
+const DECLARATION_ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
 const TEXT_MIME = new Set(['text/css', 'application/javascript', 'text/html', 'image/svg+xml', 'text/plain']);
 export const validId = (v) => typeof v === 'string' && ID_RE.test(v.trim());
 const warn = (d, code, source) => { if (d && !d.warnings.some((w) => w.code === code && w.source === source))
@@ -83,6 +88,41 @@ function isSafeAssetUrl(value) {
             return isSafeRelativePath(decoded.slice(prefix.length));
     return false;
 }
+/**
+ * Read `<root>/<rel>` for a static route: `rel` must be a clean relative path (no dot segments or dotfiles), and the
+ * read is an anchored, symlink-free open, so a link inside the root cannot expose its target. Python
+ * `(root / rel).resolve()`: a symlinked file is served when its target stays inside the root, never otherwise.
+ */
+export function readContainedFile(root, rel) {
+    if (!isSafeRelativePath(rel))
+        return null;
+    const anchor = resolvePathLikePython(root);
+    let file = resolve(anchor, rel);
+    if (!file.startsWith(anchor + sep))
+        return null;
+    const real = resolvePathLikePython(file);
+    if (real !== file) {
+        if (!real.startsWith(anchor + sep))
+            return null;
+        file = real;
+    }
+    let fd;
+    try {
+        fd = openAnchoredFd(anchor, file, { wantDir: false });
+    }
+    catch {
+        return null;
+    }
+    try {
+        return fstatSync(fd).isFile() ? { body: readFileSync(fd), file } : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 /**
  * Python `_normalize_loopback_sidecar_origin` (`urlsplit`, not WHATWG): scheme + literal loopback host + optional
  * numeric port, nothing else — no path (not even `/`), no query, no fragment, no userinfo, no host aliases.
@@ -144,7 +184,7 @@ export function normalizeProxyPath(value) {
     const segments = decoded.split('/').slice(1);
     return segments.length && segments.every((s) => s && s !== '.' && s !== '..') ? candidate : null;
 }
-const text = (v, max = 160) => (typeof v === 'string' ? v.replaceAll(/[\x00-\x1f\x7f]/g, '').trim().slice(0, max) : '');
+export const text = (v, max = 160) => (typeof v === 'string' ? v.replaceAll(/[\x00-\x1f\x7f]/g, '').trim().slice(0, max) : '');
 const entryText = (e, k) => (typeof e[k] === 'string' ? e[k].trim() : '');
 const storageOwned = (e) => isDict(e.permissions) && isDict(e.permissions.storage) && e.permissions.storage.owned === true;
 function settingsSchema(entry) {
@@ -268,6 +308,28 @@ function sidecarFromEntry(entry, d) {
     }
     return { id: entryText(entry, 'id'), name: entryText(entry, 'name'), type: 'loopback', origin, health_path: healthPath, health_url: `${origin}${healthPath}`, proxy_auth: proxyAuth };
 }
+/**
+ * A manifest `theme` reduced to the frontend skin contract: allowlisted tokens whose values pass the shared value check,
+ * keyed `<extension-id>:<key>` so it never collides with a built-in skin or another extension's skin.
+ */
+function themeFromEntry(raw, id) {
+    if (!isDict(raw) || typeof raw.key !== 'string' || !DECLARATION_ID_RE.test(raw.key))
+        return null;
+    const name = text(raw.name, 40);
+    const tokens = isDict(raw.tokens) ? Object.fromEntries(Object.entries(raw.tokens).filter(([k, v]) => SKIN_TOKENS.has(k) && typeof v === 'string' && SKIN_VALUE_RE.test(v))) : {};
+    if (!name || !Object.keys(tokens).length)
+        return null;
+    const colors = Array.isArray(raw.colors) ? raw.colors.filter((c) => typeof c === 'string' && SKIN_VALUE_RE.test(c)).slice(0, 3) : null;
+    return { key: `${id}:${raw.key}`, name, ...(raw.scheme === 'light' || raw.scheme === 'dark' ? { scheme: raw.scheme } : {}), ...(colors ? { colors } : {}), tokens };
+}
+function ttsFromEntry(raw) {
+    if (!isDict(raw) || typeof raw.id !== 'string' || !DECLARATION_ID_RE.test(raw.id))
+        return null;
+    const label = text(raw.label, 60);
+    return label ? { id: raw.id, label } : null;
+}
+/** Entries the gallery loader read from `<root>/<id>/`, keyed by object so a manifest can never claim gallery provenance. */
+const galleryFolders = new WeakMap();
 export class ExtensionService {
     deps;
     registryCache = null;
@@ -278,8 +340,7 @@ export class ExtensionService {
         this.deps = deps;
     }
     get defaultRoot() { return join(this.deps.stateDir, 'extensions'); }
-    get stateFile() { return join(this.deps.stateDir, 'extension-overrides.json'); }
-    get installFile() { return join(this.deps.stateDir, 'extension-install-manifest.json'); }
+    revisions = new Map();
     root() {
         const raw = (this.deps.env.HERMES_WEBUI_EXTENSION_DIR ?? '').trim();
         if (raw) {
@@ -304,22 +365,25 @@ export class ExtensionService {
             return null;
         }
     }
-    loadState(d) {
+    async loadState(d) {
         const empty = { version: 1, disabled_extensions: [], sidecar_proxy_consents: {} };
         const src = 'extension_state';
         let parsed;
         try {
-            if (!existsSync(this.stateFile) || !statSync(this.stateFile).isFile())
+            const record = await readDocument(this.deps.documents, 'extensions', 'overrides', { replaceInvalid: true, maxBytes: MAX_STATE_BYTES });
+            this.revisions.set('overrides', record?.revision ?? null);
+            if (!record)
                 return empty;
-            const raw = readFileSync(this.stateFile);
-            if (raw.length > MAX_STATE_BYTES) {
+            if (Buffer.byteLength(JSON.stringify(record.value)) > MAX_STATE_BYTES) {
                 warn(d, 'extension_state_oversized', src);
                 return empty;
             }
-            parsed = JSON.parse(raw.toString('utf8'));
+            parsed = record.value;
         }
-        catch {
-            warn(d, 'extension_state_unreadable', src);
+        catch (error) {
+            if (error instanceof InvalidDocument && error.reason === 'too-large')
+                this.revisions.set('overrides', error.revision);
+            warn(d, error instanceof InvalidDocument && error.reason === 'too-large' ? 'extension_state_oversized' : 'extension_state_unreadable', src);
             return empty;
         }
         if (!isDict(parsed)) {
@@ -379,19 +443,17 @@ export class ExtensionService {
             warn(d, 'extension_state_invalid_entries', src);
         return { version: 1, disabled_extensions: disabled, sidecar_proxy_consents: consents };
     }
-    writeState(state) {
-        mkdirSync(this.deps.stateDir, { recursive: true });
-        atomicWriteText(this.stateFile, JSON.stringify({ version: 1, disabled_extensions: [...new Set(state.disabled_extensions.filter(validId))].sort(), sidecar_proxy_consents: state.sidecar_proxy_consents }, null, 2));
+    async writeState(state) {
+        this.revisions.set('overrides', await this.deps.documents.put('extensions', 'overrides', { version: 1, disabled_extensions: [...new Set(state.disabled_extensions.filter(validId))].sort(), sidecar_proxy_consents: state.sidecar_proxy_consents }, this.revisions.get('overrides') ?? null));
     }
-    loadInstallManifest() {
+    async loadInstallManifest() {
         const empty = { version: 1, installed: {} };
         try {
-            if (!existsSync(this.installFile))
+            const record = await readDocument(this.deps.documents, 'extensions', 'install-manifest', { replaceInvalid: true, maxBytes: MAX_INSTALL_MANIFEST_BYTES });
+            this.revisions.set('install-manifest', record?.revision ?? null);
+            if (!record || Buffer.byteLength(JSON.stringify(record.value)) > MAX_INSTALL_MANIFEST_BYTES)
                 return empty;
-            const raw = readFileSync(this.installFile);
-            if (raw.length > MAX_INSTALL_MANIFEST_BYTES)
-                return empty;
-            const parsed = JSON.parse(raw.toString('utf8'));
+            const parsed = record.value;
             if (!isDict(parsed) || !isDict(parsed.installed))
                 return empty;
             const installed = {};
@@ -404,13 +466,14 @@ export class ExtensionService {
             }
             return { version: 1, installed };
         }
-        catch {
+        catch (error) {
+            if (error instanceof InvalidDocument && error.reason === 'too-large')
+                this.revisions.set('install-manifest', error.revision);
             return empty;
         }
     }
-    writeInstallManifest(manifest) {
-        mkdirSync(this.deps.stateDir, { recursive: true });
-        atomicWriteText(this.installFile, JSON.stringify(manifest, null, 2));
+    async writeInstallManifest(manifest) {
+        this.revisions.set('install-manifest', await this.deps.documents.put('extensions', 'install-manifest', manifest, this.revisions.get('install-manifest') ?? null));
     }
     manifestPath(root) {
         const raw = (this.deps.env.HERMES_WEBUI_EXTENSION_MANIFEST ?? '').trim();
@@ -431,16 +494,17 @@ export class ExtensionService {
             return [null, 'invalid_path'];
         return [manifest, 'configured'];
     }
-    galleryManifest(root, d) {
-        const installed = this.loadInstallManifest().installed;
+    async galleryManifest(root, d) {
+        const installed = (await this.loadInstallManifest()).installed;
         const entries = [];
         for (const id of Object.keys(installed).sort()) {
             if (!validId(id))
                 continue;
-            const file = join(root, id, 'manifest.json');
+            // `manifest.json` wins; a gallery zip may ship only `extension.json` (docs/EXTENSIONS.md).
             let manifest;
             try {
-                if (!existsSync(file) || !statSync(file).isFile()) {
+                const file = ['manifest.json', 'extension.json'].map((name) => join(root, id, name)).find((p) => existsSync(p) && statSync(p).isFile());
+                if (!file) {
                     warn(d, 'gallery_manifest_missing', 'gallery');
                     continue;
                 }
@@ -457,17 +521,26 @@ export class ExtensionService {
             }
             const withBase = (entry) => {
                 const copy = { ...entry };
+                // Paths already rooted at the id (the `extensions.json` shape, as in the shipped example) are not prefixed twice.
+                const rebase = (v) => {
+                    if (typeof v !== 'string' || !v.trim() || /^[a-z]+:|^\/\/|^\//i.test(v.trim()))
+                        return v;
+                    return v.trim().startsWith(`${id}/`) ? v.trim() : `${id}/${v.trim()}`;
+                };
                 for (const key of ['scripts', 'stylesheets'])
                     if (Array.isArray(copy[key]))
-                        copy[key] = copy[key].map((v) => (typeof v === 'string' && v.trim() && !/^[a-z]+:|^\/\/|^\//i.test(v.trim()) ? `${id}/${v.trim()}` : v));
+                        copy[key] = copy[key].map(rebase);
+                if (typeof copy.panel === 'string')
+                    copy.panel = rebase(copy.panel.trim().replace(/^(\.\/)+/, ''));
+                galleryFolders.set(copy, id);
                 return copy;
             };
             if (isDict(manifest)) {
                 const top = { id };
-                for (const key of ['name', 'enabled', 'scripts', 'stylesheets', 'sidecar', 'permissions', 'settings_schema'])
+                for (const key of ['name', 'enabled', 'version', 'description', 'panel', 'nav', 'capabilities', 'scripts', 'stylesheets', 'sidecar', 'theme', 'tts', 'permissions', 'settings_schema'])
                     if (key in manifest)
                         top[key] = manifest[key];
-                if (['scripts', 'stylesheets', 'sidecar', 'permissions', 'settings_schema'].some((k) => k in top))
+                if (['panel', 'scripts', 'stylesheets', 'sidecar', 'theme', 'tts', 'permissions', 'settings_schema'].some((k) => k in top))
                     entries.push(withBase(top));
             }
             for (const entry of manifestEntries(manifest)) {
@@ -479,14 +552,14 @@ export class ExtensionService {
         }
         return entries.length ? { extensions: entries } : null;
     }
-    loadManifest(root, d) {
+    async loadManifest(root, d) {
         const [file, pathStatus] = this.manifestPath(root);
         const status = { configured: pathStatus !== 'not_configured', loaded: false, status: pathStatus, _asset_base: '', entry_count: 0, script_count: 0, stylesheet_count: 0, sidecar_count: 0 };
         if (!file) {
             if (pathStatus === 'invalid_path')
                 warn(d, 'manifest_invalid_path', 'manifest');
             else if (pathStatus === 'not_configured') {
-                const gallery = this.galleryManifest(root, d);
+                const gallery = (await this.galleryManifest(root, d));
                 if (gallery)
                     return [gallery, { ...status, loaded: true, status: 'gallery_installed' }];
             }
@@ -650,9 +723,9 @@ export class ExtensionService {
                         break;
                     }
         }
-        const { records } = await this.sidecarRecords(manifest, disabled, state, d);
+        const { records, byId } = await this.sidecarRecords(manifest, disabled, state, d);
         Object.assign(status, { loaded: true, status: str(status.status) || 'loaded', script_count: scripts.length, stylesheet_count: stylesheets.length, sidecar_count: records.length });
-        return { scripts, stylesheets, sidecars: records };
+        return { scripts, stylesheets, sidecars: records, sidecarsById: byId };
     }
     /** Python `get_extension_status`. */
     /** Python `get_extension_config()["enabled"]` for the bootstrap feature flag: a valid root with a loadable manifest. */
@@ -661,33 +734,37 @@ export class ExtensionService {
         return this.root() !== null;
     }
     async status() {
+        return (await this.snapshot()).status;
+    }
+    /** The status payload plus the manifest and sidecar records it was built from, so `manifests()` reads the same load. */
+    async snapshot() {
         const d = { warnings: [] };
         const envDir = (this.deps.env.HERMES_WEBUI_EXTENSION_DIR ?? '').trim();
         const root = this.root();
-        const state = this.loadState(d);
+        const state = (await this.loadState(d));
         const disabled = new Set(state.disabled_extensions);
         const manifestConfigured = Boolean((this.deps.env.HERMES_WEBUI_EXTENSION_MANIFEST ?? '').trim());
         if (envDir && !root)
             warn(d, 'extension_dir_unavailable', 'extension_dir');
         if (!root) {
-            return { enabled: false, extension_dir_configured: true, extension_dir_valid: false, script_urls: [], stylesheet_urls: [], sidecars: [], counts: { script_urls: 0, stylesheet_urls: 0, sidecars: 0, manifest_extensions: 0, user_disabled: 0 }, manifest: { configured: manifestConfigured, loaded: false, status: manifestConfigured ? 'extension_disabled' : 'not_configured', entry_count: 0, script_count: 0, stylesheet_count: 0, sidecar_count: 0 }, extensions: [], warnings: d.warnings };
+            return { manifest: null, assetBase: '', sidecarsById: new Map(), status: { enabled: false, extension_dir_configured: true, extension_dir_valid: false, script_urls: [], stylesheet_urls: [], sidecars: [], counts: { script_urls: 0, stylesheet_urls: 0, sidecars: 0, manifest_extensions: 0, user_disabled: 0 }, manifest: { configured: manifestConfigured, loaded: false, status: manifestConfigured ? 'extension_disabled' : 'not_configured', entry_count: 0, script_count: 0, stylesheet_count: 0, sidecar_count: 0 }, extensions: [], warnings: d.warnings } };
         }
-        const [manifest, status] = this.loadManifest(root, d);
+        const [manifest, status] = (await this.loadManifest(root, d));
         const consentIds = new Set(Object.keys(state.sidecar_proxy_consents));
         const ext = manifest !== null ? this.extensionState(manifest, disabled, d, consentIds) : { extensions: [], knownIds: new Set(), manifestDisabled: new Set() };
-        const urls = manifest !== null ? await this.manifestUrls(manifest, status, disabled, state, d) : { scripts: [], stylesheets: [], sidecars: [] };
+        const urls = manifest !== null ? await this.manifestUrls(manifest, status, disabled, state, d) : { scripts: [], stylesheets: [], sidecars: [], sidecarsById: new Map() };
         const scriptUrls = this.envUrls('HERMES_WEBUI_EXTENSION_SCRIPT_URLS', urls.scripts.length ? urls.scripts : null, d);
         const stylesheetUrls = this.envUrls('HERMES_WEBUI_EXTENSION_STYLESHEET_URLS', urls.stylesheets.length ? urls.stylesheets : null, d);
         const publicStatus = Object.fromEntries(Object.entries(status).filter(([k]) => !k.startsWith('_')));
-        return {
-            enabled: true, extension_dir_configured: true, extension_dir_valid: true, script_urls: scriptUrls, stylesheet_urls: stylesheetUrls, sidecars: urls.sidecars,
-            counts: { script_urls: scriptUrls.length, stylesheet_urls: stylesheetUrls.length, sidecars: urls.sidecars.length, manifest_extensions: ext.extensions.length, user_disabled: [...disabled].filter((id) => ext.knownIds.has(id)).length },
-            manifest: publicStatus, extensions: ext.extensions, gallery_installed: this.loadInstallManifest().installed, warnings: d.warnings,
-        };
+        return { manifest, assetBase: str(status._asset_base), sidecarsById: urls.sidecarsById, status: {
+                enabled: true, extension_dir_configured: true, extension_dir_valid: true, script_urls: scriptUrls, stylesheet_urls: stylesheetUrls, sidecars: urls.sidecars,
+                counts: { script_urls: scriptUrls.length, stylesheet_urls: stylesheetUrls.length, sidecars: urls.sidecars.length, manifest_extensions: ext.extensions.length, user_disabled: [...disabled].filter((id) => ext.knownIds.has(id)).length },
+                manifest: publicStatus, extensions: ext.extensions, gallery_installed: (await this.loadInstallManifest()).installed, warnings: d.warnings,
+            } };
     }
-    loaded(root, d) {
-        const state = this.loadState(d);
-        const [manifest, status] = this.loadManifest(root, d);
+    async loaded(root, d) {
+        const state = (await this.loadState(d));
+        const [manifest, status] = (await this.loadManifest(root, d));
         if (manifest === null || status.loaded !== true)
             throw new ExtensionError('Extension manifest is not loaded', 409);
         return { manifest, state, disabled: new Set(state.disabled_extensions) };
@@ -702,14 +779,14 @@ export class ExtensionService {
             throw new ExtensionError('Invalid extension id', 400);
         if (typeof enabled !== 'boolean')
             throw new ExtensionError('enabled must be a boolean', 400);
-        return this.mutateState(async () => this.setEnabledLocked(idRaw.trim(), enabled));
+        return this.mutateState(async () => (await this.setEnabledLocked(idRaw.trim(), enabled)));
     }
     async setEnabledLocked(id, enabled) {
         const root = this.root();
         if (!root)
             throw new ExtensionError('Extensions are not configured', 404);
         const d = { warnings: [] };
-        const { manifest, state, disabled } = this.loaded(root, d);
+        const { manifest, state, disabled } = (await this.loaded(root, d));
         const ext = this.extensionState(manifest, disabled, d, new Set(Object.keys(state.sidecar_proxy_consents)));
         if (!ext.knownIds.has(id))
             throw new ExtensionError('Extension not found', 404);
@@ -719,7 +796,7 @@ export class ExtensionService {
             disabled.delete(id);
         else
             disabled.add(id);
-        this.writeState({ disabled_extensions: [...disabled], sidecar_proxy_consents: Object.fromEntries(Object.entries(state.sidecar_proxy_consents).filter(([k]) => ext.knownIds.has(k))) });
+        await this.writeState({ disabled_extensions: [...disabled], sidecar_proxy_consents: Object.fromEntries(Object.entries(state.sidecar_proxy_consents).filter(([k]) => ext.knownIds.has(k))) });
         return this.status();
     }
     setConsent(idRaw, approved) {
@@ -727,14 +804,14 @@ export class ExtensionService {
             throw new ExtensionError('Invalid extension id', 400);
         if (typeof approved !== 'boolean')
             throw new ExtensionError('approved must be a boolean', 400);
-        return this.mutateState(() => this.setConsentLocked(idRaw.trim(), approved));
+        return this.mutateState(async () => (await this.setConsentLocked(idRaw.trim(), approved)));
     }
     async setConsentLocked(id, approved) {
         const root = this.root();
         if (!root)
             throw new ExtensionError('Extensions are not configured', 404);
         const d = { warnings: [] };
-        const { manifest, state, disabled } = this.loaded(root, d);
+        const { manifest, state, disabled } = (await this.loaded(root, d));
         const consents = { ...state.sidecar_proxy_consents };
         const ext = this.extensionState(manifest, disabled, d, new Set(Object.keys(consents)));
         if (!ext.knownIds.has(id))
@@ -752,7 +829,7 @@ export class ExtensionService {
         }
         else
             Reflect.deleteProperty(consents, id);
-        this.writeState({ disabled_extensions: [...disabled], sidecar_proxy_consents: Object.fromEntries(Object.entries(consents).filter(([k]) => ext.knownIds.has(k))) });
+        await this.writeState({ disabled_extensions: [...disabled], sidecar_proxy_consents: Object.fromEntries(Object.entries(consents).filter(([k]) => ext.knownIds.has(k))) });
         return this.status();
     }
     /** Python `resolve_extension_sidecar_proxy_target` (legacy proxy auth only). */
@@ -767,7 +844,7 @@ export class ExtensionService {
             throw new ExtensionError('Extensions are not configured', 404);
         const id = idRaw.trim();
         const d = { warnings: [] };
-        const { manifest, state, disabled } = this.loaded(root, d);
+        const { manifest, state, disabled } = (await this.loaded(root, d));
         const ext = this.extensionState(manifest, disabled, d, new Set(Object.keys(state.sidecar_proxy_consents)));
         if (!ext.knownIds.has(id))
             throw new ExtensionError('Extension not found', 404);
@@ -833,233 +910,219 @@ export class ExtensionService {
         }
     }
     async install(idRaw, downloadUrl, sha256) {
-        if (!validId(idRaw))
-            throw new ExtensionError('Invalid extension id');
-        const id = idRaw.trim();
-        if (typeof downloadUrl !== 'string' || !downloadUrl.startsWith('https://'))
-            throw new ExtensionError('Invalid download URL');
-        let host = '';
-        try {
-            host = new URL(downloadUrl).hostname;
-        }
-        catch {
-            host = '';
-        }
-        if (!ALLOWED_DOWNLOAD_HOSTS.has(host))
-            throw new ExtensionError('Invalid download URL');
-        if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256))
-            throw new ExtensionError('Invalid sha256');
-        const root = this.writableRoot();
-        if (!root)
-            throw new ExtensionError('Extensions not configured', 404);
-        let raw;
-        try {
-            const res = await this.galleryFetch(downloadUrl, 30_000);
-            if (!res.ok)
-                throw new Error(`download ${String(res.status)}`);
-            const capped = await readCapped(res, MAX_ZIP_BYTES);
-            if (!capped)
-                throw new ExtensionError('Download too large');
-            raw = capped;
-        }
-        catch (error) {
-            throw new ExtensionError(error instanceof ExtensionError ? error.message : 'Download failed', error instanceof ExtensionError ? error.status : 502);
-        }
-        if (createHash('sha256').update(raw).digest('hex') !== sha256)
-            throw new ExtensionError('SHA-256 mismatch');
-        let entries;
-        try {
-            entries = readZip(raw);
-        }
-        catch {
-            throw new ExtensionError('Invalid zip archive');
-        }
-        const files = entries.filter((e) => e.name && !e.isDir);
-        if (files.reduce((acc, e) => acc + e.size, 0) > MAX_ZIP_BYTES * 10)
-            throw new ExtensionError('Archive uncompressed size exceeds limit');
-        if (files.length > 1024)
-            throw new ExtensionError('Archive contains too many files');
-        const prefix = files.every((e) => e.name.startsWith(`${id}/`)) ? `${id}/` : '';
-        const stripped = (name) => (prefix && name.startsWith(prefix) ? name.slice(prefix.length) : name);
-        const anchor = resolvePathLikePython(root);
-        const extDir = resolve(anchor, id);
-        for (const e of files) {
-            const decoded = fullyUnquote(stripped(e.name));
-            if (!decoded || !isSafeArchiveMember(decoded))
-                throw new ExtensionError('Unsafe archive member');
-            const target = resolve(extDir, decoded);
-            if (!target.startsWith(anchor + sep) || !target.startsWith(extDir + sep))
-                throw new ExtensionError('Zip-slip detected');
-        }
-        let version = 'unknown';
-        for (const vfile of ['extension.json', 'manifest.json']) {
-            const entry = entries.find((e) => e.name === prefix + vfile);
-            if (!entry)
-                continue;
+        return await this.mutateState(async () => {
+            if (!validId(idRaw))
+                throw new ExtensionError('Invalid extension id');
+            const id = idRaw.trim();
+            if (typeof downloadUrl !== 'string' || !downloadUrl.startsWith('https://'))
+                throw new ExtensionError('Invalid download URL');
+            let host = '';
             try {
-                const m = JSON.parse(entry.read().toString('utf8'));
-                if (isDict(m) && typeof m.version === 'string') {
-                    version = m.version;
-                    break;
-                }
+                host = new URL(downloadUrl).hostname;
             }
-            catch { /* ignore */ }
-        }
-        try {
-            if (lstatSync(extDir).isSymbolicLink())
-                throw new ExtensionError('Extension directory is a symlink', 400);
-        }
-        catch (error) {
-            if (error instanceof ExtensionError)
-                throw error;
-        }
-        try {
-            makeAnchoredDir(anchor, extDir);
-        }
-        catch {
-            throw new ExtensionError('Extension directory is a symlink', 400);
-        }
-        const written = [];
-        const rollback = () => {
-            for (const p of written) {
-                try {
-                    unlinkAnchored(anchor, p);
-                }
-                catch { /* gone */ }
+            catch {
+                host = '';
             }
+            if (!ALLOWED_DOWNLOAD_HOSTS.has(host))
+                throw new ExtensionError('Invalid download URL');
+            if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256))
+                throw new ExtensionError('Invalid sha256');
+            const root = this.writableRoot();
+            if (!root)
+                throw new ExtensionError('Extensions not configured', 404);
+            let raw;
             try {
-                rmdirAnchored(anchor, extDir);
+                const res = await this.galleryFetch(downloadUrl, 30_000);
+                if (!res.ok)
+                    throw new Error(`download ${String(res.status)}`);
+                const capped = await readCapped(res, MAX_ZIP_BYTES);
+                if (!capped)
+                    throw new ExtensionError('Download too large');
+                raw = capped;
             }
-            catch { /* not empty, or gone */ }
-        };
-        try {
-            // Every destination is created or truncated through the anchored walk from the extension root, so a symlink
-            // already inside the extension (or a parent swapped mid-extraction) can never redirect a write outside it.
+            catch (error) {
+                throw new ExtensionError(error instanceof ExtensionError ? error.message : 'Download failed', error instanceof ExtensionError ? error.status : 502);
+            }
+            if (createHash('sha256').update(raw).digest('hex') !== sha256)
+                throw new ExtensionError('SHA-256 mismatch');
+            let entries;
+            try {
+                entries = readZip(raw);
+            }
+            catch {
+                throw new ExtensionError('Invalid zip archive');
+            }
+            const files = entries.filter((e) => e.name && !e.isDir);
+            if (files.reduce((acc, e) => acc + e.size, 0) > MAX_ZIP_BYTES * 10)
+                throw new ExtensionError('Archive uncompressed size exceeds limit');
+            if (files.length > 1024)
+                throw new ExtensionError('Archive contains too many files');
+            const prefix = files.every((e) => e.name.startsWith(`${id}/`)) ? `${id}/` : '';
+            const stripped = (name) => (prefix && name.startsWith(prefix) ? name.slice(prefix.length) : name);
+            const anchor = resolvePathLikePython(root);
+            const extDir = resolve(anchor, id);
             for (const e of files) {
-                const dest = resolve(extDir, fullyUnquote(stripped(e.name)));
-                let fd;
+                const decoded = fullyUnquote(stripped(e.name));
+                if (!decoded || !isSafeArchiveMember(decoded))
+                    throw new ExtensionError('Unsafe archive member');
+                const target = resolve(extDir, decoded);
+                if (!target.startsWith(anchor + sep) || !target.startsWith(extDir + sep))
+                    throw new ExtensionError('Zip-slip detected');
+            }
+            let version = 'unknown';
+            for (const vfile of ['extension.json', 'manifest.json']) {
+                const entry = entries.find((e) => e.name === prefix + vfile);
+                if (!entry)
+                    continue;
                 try {
-                    fd = openAnchoredCreateFd(anchor, dest);
+                    const m = JSON.parse(entry.read().toString('utf8'));
+                    if (isDict(m) && typeof m.version === 'string') {
+                        version = m.version;
+                        break;
+                    }
                 }
-                catch (error) {
-                    if (!(error instanceof FileExistsError))
-                        throw error;
-                    fd = openAnchoredWriteFd(anchor, dest);
+                catch { /* ignore */ }
+            }
+            try {
+                if (lstatSync(extDir).isSymbolicLink())
+                    throw new ExtensionError('Extension directory is a symlink', 400);
+            }
+            catch (error) {
+                if (error instanceof ExtensionError)
+                    throw error;
+            }
+            try {
+                makeAnchoredDir(anchor, extDir);
+            }
+            catch {
+                throw new ExtensionError('Extension directory is a symlink', 400);
+            }
+            const written = [];
+            const rollback = () => {
+                for (const p of written) {
+                    try {
+                        unlinkAnchored(anchor, p);
+                    }
+                    catch { /* gone */ }
                 }
                 try {
-                    writeFileSync(fd, e.read());
+                    rmdirAnchored(anchor, extDir);
                 }
-                finally {
-                    closeSync(fd);
+                catch { /* not empty, or gone */ }
+            };
+            try {
+                // Every destination is created or truncated through the anchored walk from the extension root, so a symlink
+                // already inside the extension (or a parent swapped mid-extraction) can never redirect a write outside it.
+                for (const e of files) {
+                    const dest = resolve(extDir, fullyUnquote(stripped(e.name)));
+                    let fd;
+                    try {
+                        fd = openAnchoredCreateFd(anchor, dest);
+                    }
+                    catch (error) {
+                        if (!(error instanceof FileExistsError))
+                            throw error;
+                        fd = openAnchoredWriteFd(anchor, dest);
+                    }
+                    try {
+                        writeFileSync(fd, e.read());
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    written.push(dest);
                 }
-                written.push(dest);
             }
-        }
-        catch {
-            rollback();
-            throw new ExtensionError('Extraction failed', 500);
-        }
-        try {
-            const manifest = this.loadInstallManifest();
-            const record = { version, files: written.map((p) => relative(extDir, p).split(sep).join('/')), installed_at: new Date().toISOString() };
-            const next = { version: 1, installed: { ...manifest.installed, [id]: record } };
-            if (Buffer.byteLength(JSON.stringify(next, null, 2)) > MAX_INSTALL_MANIFEST_BYTES)
-                throw new ExtensionError('Install manifest would exceed size limit');
-            this.writeInstallManifest(next);
-        }
-        catch (error) {
-            rollback();
-            throw error instanceof ExtensionError ? error : new ExtensionError('Failed to record install', 500);
-        }
-        return { installed: true, id, version };
-    }
-    uninstall(idRaw) {
-        if (!validId(idRaw))
-            throw new ExtensionError('Invalid extension id');
-        const id = idRaw.trim();
-        const root = this.root();
-        if (!root)
-            throw new ExtensionError('Extensions not configured', 404);
-        const manifest = this.loadInstallManifest();
-        const entry = manifest.installed[id];
-        if (!entry)
-            throw new ExtensionError('Extension not installed', 404);
-        const anchor = resolvePathLikePython(root);
-        const extDir = resolve(anchor, id);
-        for (const rel of entry.files) {
-            if (!isSafeArchiveMember(rel))
-                continue;
-            const target = resolve(extDir, rel);
-            if (!target.startsWith(extDir + sep))
-                continue;
-            try {
-                unlinkAnchored(anchor, target);
+            catch {
+                rollback();
+                throw new ExtensionError('Extraction failed', 500);
             }
-            catch { /* gone */ }
-        }
-        // Prune now-empty directories, enumerating and removing each through the anchored walk so a directory replaced by
-        // a symlink is skipped rather than followed into its target.
-        const prune = (dir) => {
-            let subdirs;
             try {
-                subdirs = withAnchoredDir(anchor, dir, (child) => readdirSync(child('.'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name));
+                const manifest = (await this.loadInstallManifest());
+                const record = { version, files: written.map((p) => relative(extDir, p).split(sep).join('/')), installed_at: new Date().toISOString() };
+                const next = { version: 1, installed: { ...manifest.installed, [id]: record } };
+                if (Buffer.byteLength(JSON.stringify(next, null, 2)) > MAX_INSTALL_MANIFEST_BYTES)
+                    throw new ExtensionError('Install manifest would exceed size limit');
+                await this.writeInstallManifest(next);
             }
-            catch {
-                return;
+            catch (error) {
+                rollback();
+                throw error instanceof ExtensionError ? error : new ExtensionError('Failed to record install', 500);
             }
-            for (const name of subdirs)
-                prune(join(dir, name));
-            try {
-                rmdirAnchored(anchor, dir);
+            return { installed: true, id, version };
+        });
+    }
+    async uninstall(idRaw) {
+        return await this.mutateState(async () => {
+            if (!validId(idRaw))
+                throw new ExtensionError('Invalid extension id');
+            const id = idRaw.trim();
+            const root = this.root();
+            if (!root)
+                throw new ExtensionError('Extensions not configured', 404);
+            const manifest = (await this.loadInstallManifest());
+            const entry = manifest.installed[id];
+            if (!entry)
+                throw new ExtensionError('Extension not installed', 404);
+            const anchor = resolvePathLikePython(root);
+            const extDir = resolve(anchor, id);
+            for (const rel of entry.files) {
+                if (!isSafeArchiveMember(rel))
+                    continue;
+                const target = resolve(extDir, rel);
+                if (!target.startsWith(extDir + sep))
+                    continue;
+                try {
+                    unlinkAnchored(anchor, target);
+                }
+                catch { /* gone */ }
             }
-            catch { /* not empty, or gone */ }
-        };
-        prune(extDir);
-        Reflect.deleteProperty(manifest.installed, id);
-        this.writeInstallManifest(manifest);
-        return { uninstalled: true, id };
+            // Prune now-empty directories, enumerating and removing each through the anchored walk so a directory replaced by
+            // a symlink is skipped rather than followed into its target.
+            const prune = (dir) => {
+                let subdirs;
+                try {
+                    subdirs = withAnchoredDir(anchor, dir, (child) => readdirSync(child('.'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name));
+                }
+                catch {
+                    return;
+                }
+                for (const name of subdirs)
+                    prune(join(dir, name));
+                try {
+                    rmdirAnchored(anchor, dir);
+                }
+                catch { /* not empty, or gone */ }
+            };
+            prune(extDir);
+            Reflect.deleteProperty(manifest.installed, id);
+            await this.writeInstallManifest(manifest);
+            return { uninstalled: true, id };
+        });
     }
     /** Python `serve_extension_static`: bytes, MIME, sandbox CSP for HTML; null means 404. */
     staticFile(rel) {
         const root = this.root();
-        if (!root || !isSafeRelativePath(rel))
+        const found = root ? readContainedFile(root, rel) : null;
+        if (!found)
             return null;
-        // Python `serve_extension_static`: an anchored, symlink-free open so a link inside the extension dir cannot expose its target.
-        const anchor = resolvePathLikePython(root);
-        let file = resolve(anchor, rel);
-        if (!file.startsWith(anchor + sep))
-            return null;
-        // Python `(root / rel).resolve()`: a symlinked asset is served when its target stays inside the root, never otherwise.
-        const real = resolvePathLikePython(file);
-        if (real !== file) {
-            if (!real.startsWith(anchor + sep))
-                return null;
-            file = real;
-        }
-        let fd;
-        try {
-            fd = openAnchoredFd(anchor, file, { wantDir: false });
-        }
-        catch {
-            return null;
-        }
-        try {
-            if (!fstatSync(fd).isFile())
-                return null;
-            const ext = file.slice(file.lastIndexOf('.') + 1).toLowerCase();
-            const ct = EXTENSION_MIME[ext] ?? 'text/plain';
-            return { body: readFileSync(fd), contentType: TEXT_MIME.has(ct) ? `${ct}; charset=utf-8` : ct, html: ct === 'text/html' };
-        }
-        catch {
-            return null;
-        }
-        finally {
-            closeSync(fd);
-        }
+        const ext = found.file.slice(found.file.lastIndexOf('.') + 1).toLowerCase();
+        const ct = EXTENSION_MIME[ext] ?? 'text/plain';
+        return { body: found.body, contentType: TEXT_MIME.has(ct) ? `${ct}; charset=utf-8` : ct, html: ct === 'text/html' };
     }
-    /** Python `api/extension_manifests.build_manifests` (extension entries only; dashboard plugins were dropped). */
+    /** Python `api/extension_manifests.build_manifests` extension entries (the manifests route appends dashboard plugins). */
     async manifests() {
-        const status = await this.status();
+        const { status, manifest, assetBase, sidecarsById } = await this.snapshot();
+        // Status rows carry only enable state; panel, nav, capabilities, assets, and metadata come from the first manifest entry per id.
+        const rawById = new Map();
+        for (const e of manifestEntries(manifest)) {
+            const id = entryText(e, 'id');
+            if (!rawById.has(id))
+                rawById.set(id, e);
+        }
+        // Gallery rows are the entries the gallery loader read from their own install folder; `uninstall` accepts exactly the
+        // ids in the install manifest, so a configured entry that shares an installed id never offers Uninstall.
+        const installed = isDict(status.gallery_installed) ? status.gallery_installed : {};
         const manifests = [];
         const seen = new Set();
         const ID = /^[a-z][a-z0-9_-]{0,63}$/;
@@ -1068,27 +1131,42 @@ export class ExtensionService {
             if (!ID.test(id) || seen.has(id))
                 continue;
             seen.add(id);
-            const rawManifest = isDict(entry.manifest) ? entry.manifest : entry;
+            const rawManifest = rawById.get(str(entry.id)) ?? {};
             const warnings = [];
             let panel = null;
             const rawPanel = rawManifest.panel;
             if (rawPanel !== null && rawPanel !== undefined) {
-                if (typeof rawPanel !== 'string' || !/^[A-Za-z0-9._/-]{1,300}$/.test(rawPanel) || rawPanel.split('/').includes('..') || rawPanel.startsWith('/'))
+                // Like scripts, a panel path is relative to the manifest's folder; gallery entries were rebased onto `<id>/`.
+                const url = typeof rawPanel === 'string' ? `extensions/${assetBase ? `${assetBase}/` : ''}${rawPanel.replace(/^(\.\/)+/, '')}` : '';
+                if (typeof rawPanel !== 'string' || !/^[A-Za-z0-9._/-]{1,300}$/.test(rawPanel) || !isSafeRelativePath(url) || url.length > 400)
                     warnings.push('panel_path_rejected');
                 else if (!rawPanel.toLowerCase().endsWith('.html'))
                     warnings.push('panel_not_html');
                 else
-                    panel = `extensions/${id}/${rawPanel.replace(/^[./]+/, '')}`;
+                    panel = url;
             }
-            const scripts = Array.isArray(entry.scripts) ? entry.scripts : Array.isArray(rawManifest.scripts) ? rawManifest.scripts : [];
-            const stylesheets = Array.isArray(entry.stylesheets) ? entry.stylesheets : Array.isArray(rawManifest.stylesheets) ? rawManifest.stylesheets : [];
-            const legacy = Boolean((scripts.length || stylesheets.length) && !panel);
+            const scripts = Array.isArray(rawManifest.scripts) ? rawManifest.scripts : [];
+            const stylesheets = Array.isArray(rawManifest.stylesheets) ? rawManifest.stylesheets : [];
+            const theme = themeFromEntry(rawManifest.theme, id);
+            if (!theme && rawManifest.theme != null)
+                warnings.push('theme_rejected');
+            // A skin is the one declaration that works without a panel, so it keeps an entry with leftover assets runnable.
+            const legacy = Boolean((scripts.length || stylesheets.length) && !panel && !theme);
             const rawNav = isDict(rawManifest.nav) ? rawManifest.nav : {};
-            const nav = panel ? { label: text(rawNav.label, 40) || text(entry.name ?? rawManifest.name, 40) || id, ...(text(rawNav.icon, 40) ? { icon: text(rawNav.icon, 40) } : {}) } : null;
-            const permissions = isDict(entry.permissions) ? Object.fromEntries(Object.entries(entry.permissions).map(([k, v]) => [k, Boolean(v)])) : {};
-            const enabledFlag = entry.effective_enabled ?? entry.enabled ?? true;
+            const nav = panel ? { label: text(rawNav.label, 40) || text(entry.name, 40) || id, ...(text(rawNav.icon, 40) ? { icon: text(rawNav.icon, 40) } : {}) } : null;
+            const permissions = isDict(rawManifest.permissions) ? Object.fromEntries(Object.entries(rawManifest.permissions).filter(([k]) => k.length <= 64).map(([k, v]) => [k, Boolean(v)])) : {};
+            const tts = ttsFromEntry(rawManifest.tts);
+            if (!tts && rawManifest.tts != null)
+                warnings.push('tts_rejected');
+            // The sidecar the proxy would serve: same record, availability, and saved consent `proxyTarget` enforces
+            // (which refuses token-v1 sidecars in this release).
+            const record = sidecarsById.get(str(entry.id));
+            const declared = isDict(record?.sidecar) && record.sidecar.proxy_auth !== 'token-v1' ? record.sidecar : null;
+            const proxy = isDict(record?.proxy) ? record.proxy : null;
+            const healthPath = declared ? str(declared.health_path) : '';
+            const sidecar = declared && proxy?.available === true ? { origin: str(declared.origin), ...(healthPath.length <= 200 ? { health_path: healthPath } : {}), consented: proxy.consented === true } : null;
             const caps = (Array.isArray(rawManifest.capabilities) ? rawManifest.capabilities : []).filter((c) => typeof c === 'string' && ['settings', 'storage', 'sidecar', 'lifecycle', 'theme', 'tts', 'navigate', 'toast', 'session'].includes(c));
-            manifests.push({ id, name: text(entry.name ?? rawManifest.name, 80) || id, version: text(entry.version ?? rawManifest.version, 40), description: text(entry.description ?? rawManifest.description, 300), source: entry.gallery_installed || entry.source === 'gallery' ? 'gallery' : 'manifest', enabled: Boolean(enabledFlag) && !legacy, panel, nav, capabilities: [...new Set(caps)], permissions, settings_schema: Array.isArray(entry.settings_schema) ? entry.settings_schema : [], theme: null, tts: null, sidecar: null, legacy_injection: legacy, warnings });
+            manifests.push({ id, name: text(entry.name, 80) || id, version: text(rawManifest.version, 40), description: text(rawManifest.description, 300), source: galleryFolders.get(rawManifest) === id && Object.hasOwn(installed, id) ? 'gallery' : 'manifest', enabled: entry.effective_enabled === true && !legacy, can_toggle: entry.can_toggle !== false && !legacy, panel, nav, capabilities: [...new Set(caps)], permissions, settings_schema: Array.isArray(entry.settings_schema) ? entry.settings_schema : [], theme, tts, sidecar, legacy_injection: legacy, warnings });
         }
         return { protocol_version: 1, manifests };
     }