diff --git a/application/i18n/locales/en/core.ts b/application/i18n/locales/en/core.ts index 6c36aa2d2..0c994c869 100644 --- a/application/i18n/locales/en/core.ts +++ b/application/i18n/locales/en/core.ts @@ -1328,6 +1328,25 @@ Highlight the focused split pane: "settings.plugins.manager.unbounded": "No narrower resource scope is declared. Check the actual scope in the permission prompt.", "settings.plugins.openView": "Open", "settings.plugins.openManager": "Open plugin manager", + "settings.plugins.sources.conflict": "This ID is installed from another source. Uninstall and explicitly reset its private data before switching. Existing source:", + "settings.plugins.sources.clearPrivate": "Also clear this source’s private data, grants and secrets to reinstall from another source. This cannot be undone.", + "settings.plugins.sources.official": "Official marketplace", + "settings.plugins.sources.thirdparty": "Third-party marketplace", + "settings.plugins.sources.manage": "Manage sources", + "settings.plugins.sources.select": "Select a source", + "settings.plugins.sources.empty": "Choose or add a third-party source.", + "settings.plugins.sources.add": "Add source", + "settings.plugins.sources.remove": "Remove source", + "settings.plugins.sources.name": "Source name", + "settings.plugins.sources.address": "HTTPS source address", + "settings.plugins.sources.risk": "Third-party sources are not maintained or endorsed by Netcatty. Review the real domain, package permissions and author before installing.", + "settings.plugins.sources.accept": "I trust this domain to supply plugin metadata and packages. This does not grant plugin permissions.", + "settings.plugins.sources.removeNote": "Installed plugins and their data remain. Updates from this source stop; another source will not replace it.", + "settings.plugins.sources.disablePlugins": "Also disable plugins installed from this source", + "settings.plugins.sources.installConfirm": "Review third-party installation", + "settings.plugins.sources.source": "Source", + "settings.plugins.sources.local": "Local import", + "settings.plugins.sources.all": "All sources", "settings.plugins.title": "Plugins", "settings.plugins.description": "Manage your plugins and explore the catalog.", 'settings.plugins.loading': 'Loading plugin settings…', diff --git a/application/i18n/locales/es/core.ts b/application/i18n/locales/es/core.ts index 7e816d83c..16e90785d 100644 --- a/application/i18n/locales/es/core.ts +++ b/application/i18n/locales/es/core.ts @@ -1328,6 +1328,25 @@ Resalta el panel dividido enfocado: "settings.plugins.manager.unbounded": "No se declara un alcance de recursos más limitado. Revisa el alcance real en la solicitud de permiso.", "settings.plugins.openView": "Abrir", "settings.plugins.openManager": "Abrir gestor de plugins", + "settings.plugins.sources.conflict": "This ID is installed from another source. Uninstall and explicitly reset its private data before switching. Existing source:", + "settings.plugins.sources.clearPrivate": "Also clear this source’s private data, grants and secrets to reinstall from another source. This cannot be undone.", + "settings.plugins.sources.official": "Official marketplace", + "settings.plugins.sources.thirdparty": "Third-party marketplace", + "settings.plugins.sources.manage": "Manage sources", + "settings.plugins.sources.select": "Select a source", + "settings.plugins.sources.empty": "Choose or add a third-party source.", + "settings.plugins.sources.add": "Add source", + "settings.plugins.sources.remove": "Remove source", + "settings.plugins.sources.name": "Source name", + "settings.plugins.sources.address": "HTTPS source address", + "settings.plugins.sources.risk": "Third-party sources are not maintained or endorsed by Netcatty. Review the real domain, package permissions and author before installing.", + "settings.plugins.sources.accept": "I trust this domain to supply plugin metadata and packages. This does not grant plugin permissions.", + "settings.plugins.sources.removeNote": "Installed plugins and their data remain. Updates from this source stop; another source will not replace it.", + "settings.plugins.sources.disablePlugins": "Also disable plugins installed from this source", + "settings.plugins.sources.installConfirm": "Review third-party installation", + "settings.plugins.sources.source": "Source", + "settings.plugins.sources.local": "Local import", + "settings.plugins.sources.all": "All sources", "settings.plugins.title": "Plugins", "settings.plugins.description": "Gestiona tus plugins y explora el catálogo.", 'settings.plugins.loading': 'Cargando ajustes del plugin…', diff --git a/application/i18n/locales/ru/core.ts b/application/i18n/locales/ru/core.ts index 40fcc46d3..ad07f9a05 100644 --- a/application/i18n/locales/ru/core.ts +++ b/application/i18n/locales/ru/core.ts @@ -1223,6 +1223,25 @@ export const ruCoreMessages: Messages = { "settings.plugins.manager.unbounded": "Более узкая область ресурсов не заявлена. Проверьте фактическую область в запросе разрешения.", "settings.plugins.openView": "Открыть", "settings.plugins.openManager": "Открыть управление плагинами", + "settings.plugins.sources.conflict": "This ID is installed from another source. Uninstall and explicitly reset its private data before switching. Existing source:", + "settings.plugins.sources.clearPrivate": "Also clear this source’s private data, grants and secrets to reinstall from another source. This cannot be undone.", + "settings.plugins.sources.official": "Official marketplace", + "settings.plugins.sources.thirdparty": "Third-party marketplace", + "settings.plugins.sources.manage": "Manage sources", + "settings.plugins.sources.select": "Select a source", + "settings.plugins.sources.empty": "Choose or add a third-party source.", + "settings.plugins.sources.add": "Add source", + "settings.plugins.sources.remove": "Remove source", + "settings.plugins.sources.name": "Source name", + "settings.plugins.sources.address": "HTTPS source address", + "settings.plugins.sources.risk": "Third-party sources are not maintained or endorsed by Netcatty. Review the real domain, package permissions and author before installing.", + "settings.plugins.sources.accept": "I trust this domain to supply plugin metadata and packages. This does not grant plugin permissions.", + "settings.plugins.sources.removeNote": "Installed plugins and their data remain. Updates from this source stop; another source will not replace it.", + "settings.plugins.sources.disablePlugins": "Also disable plugins installed from this source", + "settings.plugins.sources.installConfirm": "Review third-party installation", + "settings.plugins.sources.source": "Source", + "settings.plugins.sources.local": "Local import", + "settings.plugins.sources.all": "All sources", "settings.plugins.title": "Плагины", "settings.plugins.description": "Управляйте плагинами и просматривайте каталог.", 'settings.plugins.loading': 'Загрузка настроек плагинов…', diff --git a/application/i18n/locales/zh-CN/core.ts b/application/i18n/locales/zh-CN/core.ts index 3e5f820c7..dd870b5e3 100644 --- a/application/i18n/locales/zh-CN/core.ts +++ b/application/i18n/locales/zh-CN/core.ts @@ -1243,6 +1243,25 @@ Vaults 标签保持扁平,不使用这块背景。 "settings.plugins.manager.unbounded": "未声明更细的资源范围。请在权限提示中检查实际授权范围。", "settings.plugins.openView": "打开", "settings.plugins.openManager": "打开插件管理", + "settings.plugins.sources.conflict": "此 ID 已从其他来源安装。请先卸载并明确清理旧来源数据,再换源重装。原来源:", + "settings.plugins.sources.clearPrivate": "同时清除本来源的私有数据、授权和秘密,以便显式换源重装。此操作不可撤销。", + "settings.plugins.sources.official": "官方市场", + "settings.plugins.sources.thirdparty": "第三方市场", + "settings.plugins.sources.manage": "管理来源", + "settings.plugins.sources.select": "选择来源", + "settings.plugins.sources.empty": "选择或添加第三方来源。", + "settings.plugins.sources.add": "添加来源", + "settings.plugins.sources.remove": "移除来源", + "settings.plugins.sources.name": "来源名称", + "settings.plugins.sources.address": "HTTPS 来源地址", + "settings.plugins.sources.risk": "第三方来源不代表 Netcatty 维护或认可。安装前请核对真实域名、插件权限与作者。", + "settings.plugins.sources.accept": "我信任此域名提供插件目录和软件包。此操作不会授予插件权限。", + "settings.plugins.sources.removeNote": "保留已安装插件及数据,停止此来源更新,不会自动切换到其他来源。", + "settings.plugins.sources.disablePlugins": "同时停用来自该来源的插件", + "settings.plugins.sources.installConfirm": "确认第三方安装", + "settings.plugins.sources.source": "来源", + "settings.plugins.sources.local": "本地导入", + "settings.plugins.sources.all": "全部来源", "settings.plugins.title": "插件", "settings.plugins.description": "管理已安装插件,浏览精选目录。", 'settings.plugins.loading': '正在加载插件设置…', diff --git a/application/i18n/locales/zh-TW/core.ts b/application/i18n/locales/zh-TW/core.ts index 0049cf42b..5b6a84809 100644 --- a/application/i18n/locales/zh-TW/core.ts +++ b/application/i18n/locales/zh-TW/core.ts @@ -1217,6 +1217,25 @@ Vaults 分頁維持扁平,不使用這塊背景。 "settings.plugins.manager.unbounded": "未宣告更細的資源範圍。請在權限提示中檢查實際授權範圍。", "settings.plugins.openView": "開啟", "settings.plugins.openManager": "開啟插件管理", + "settings.plugins.sources.conflict": "此 ID 已从其他来源安装。请先卸载并明确清理旧来源数据,再换源重装。原来源:", + "settings.plugins.sources.clearPrivate": "同时清除本来源的私有数据、授权和秘密,以便显式换源重装。此操作不可撤销。", + "settings.plugins.sources.official": "官方市场", + "settings.plugins.sources.thirdparty": "第三方市场", + "settings.plugins.sources.manage": "管理来源", + "settings.plugins.sources.select": "选择来源", + "settings.plugins.sources.empty": "选择或添加第三方来源。", + "settings.plugins.sources.add": "添加来源", + "settings.plugins.sources.remove": "移除来源", + "settings.plugins.sources.name": "来源名称", + "settings.plugins.sources.address": "HTTPS 来源地址", + "settings.plugins.sources.risk": "第三方来源不代表 Netcatty 维护或认可。安装前请核对真实域名、插件权限与作者。", + "settings.plugins.sources.accept": "我信任此域名提供插件目录和软件包。此操作不会授予插件权限。", + "settings.plugins.sources.removeNote": "保留已安装插件及数据,停止此来源更新,不会自动切换到其他来源。", + "settings.plugins.sources.disablePlugins": "同时停用来自该来源的插件", + "settings.plugins.sources.installConfirm": "确认第三方安装", + "settings.plugins.sources.source": "来源", + "settings.plugins.sources.local": "本地导入", + "settings.plugins.sources.all": "全部来源", "settings.plugins.title": "插件", "settings.plugins.description": "管理已安裝插件,瀏覽精選目錄。", 'settings.plugins.loading': '正在載入外掛程式設定…', diff --git a/application/state/usePluginCatalog.test.ts b/application/state/usePluginCatalog.test.ts index 01362da28..a8b8dba7d 100644 --- a/application/state/usePluginCatalog.test.ts +++ b/application/state/usePluginCatalog.test.ts @@ -77,8 +77,8 @@ test('offline snapshot stays browsable, retry clears warning, and operations bin offline = false; await act(async () => state.retryList()); assert.equal(state.listError, null); assert.equal(state.source, 'registry'); - assert.deepEqual(reads.at(-1), [entry.id, 'second']); + assert.deepEqual(reads.at(-1), [entry.id, 'second', 'official']); await act(async () => state.install(entry.id)); - assert.deepEqual(installs, [[entry.id, 'second']]); + assert.deepEqual(installs, [[entry.id, 'second', 'official', undefined]]); await act(async () => renderer.unmount()); }); diff --git a/application/state/usePluginCatalog.ts b/application/state/usePluginCatalog.ts index bc20a4075..80b2419fb 100644 --- a/application/state/usePluginCatalog.ts +++ b/application/state/usePluginCatalog.ts @@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react'; import { netcattyBridge } from '../../infrastructure/services/netcattyBridge'; type ReadmeState = { id: string; token?: string; attempt: number; status: 'loading' | 'ready' | 'error'; text: string; error: string | null }; -export function usePluginCatalog(selectedId: string | null) { +export function usePluginCatalog(selectedId: string | null, sourceId = 'official') { const [entries, setEntries] = useState([]); const [listStatus, setListStatus] = useState<'loading' | 'ready' | 'error'>('loading'); const [source, setSource] = useState('builtin'); @@ -12,6 +12,7 @@ export function usePluginCatalog(selectedId: string | null) { const [readmeAttempt, setReadmeAttempt] = useState(0); const [installError, setInstallError] = useState<{ id: string; message: string } | null>(null); const [busy, setBusy] = useState(false); + const [sourceBinding, setSourceBinding] = useState(null); const installing = useRef(false); const mounted = useRef(false); useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []); @@ -22,12 +23,18 @@ export function usePluginCatalog(selectedId: string | null) { try { const bridge = netcattyBridge.get(); if (!bridge?.listPluginCatalog) throw new Error('Catalog browsing unavailable'); - const list = await bridge.listPluginCatalog(); + const list = await bridge.listPluginCatalog(sourceId); if (active) { setEntries(list.entries); setSource(list.source); setListError(list.error); setListStatus('ready'); } } catch (cause) { if (active) { setListStatus('error'); setListError(String(cause)); } } })(); return () => { active = false; }; - }, [listAttempt]); + }, [listAttempt, sourceId]); + useEffect(() => { + let active = true; + setSourceBinding(null); + if (selectedId) void netcattyBridge.get()?.getPluginSourceBinding?.(selectedId).then((binding) => { if (active) setSourceBinding(binding); }).catch((cause) => { if (active) setInstallError({ id: selectedId, message: String(cause) }); }); + return () => { active = false; }; + }, [selectedId, sourceId]); const selectionToken = entries.find((entry) => entry.id === selectedId)?.selectionToken; useEffect(() => { if (!selectedId) return; @@ -38,15 +45,15 @@ export function usePluginCatalog(selectedId: string | null) { try { const bridge = netcattyBridge.get(); if (!bridge?.getPluginCatalogReadme) throw new Error('README retrieval unavailable'); - const text = await bridge.getPluginCatalogReadme(selectedId, selectionToken); + const text = await bridge.getPluginCatalogReadme(selectedId, selectionToken, sourceId); if (active) setReadmeState({ ...base, status: 'ready', text }); } catch (cause) { if (active) setReadmeState({ ...base, status: 'error', error: String(cause) }); } })(); return () => { active = false; }; - }, [selectedId, selectionToken, readmeAttempt]); + }, [selectedId, selectionToken, readmeAttempt, sourceId]); const currentReadme = readmeState?.id === selectedId && readmeState.token === selectionToken && readmeState.attempt === readmeAttempt ? readmeState : null; return { - entries, listStatus, listError, source, + entries, listStatus, listError, source, sourceBinding, readme: currentReadme?.status === 'ready' ? currentReadme.text : null, readmeStatus: currentReadme?.status ?? (selectedId ? 'loading' : 'idle'), readmeError: currentReadme?.error ?? null, @@ -54,14 +61,19 @@ export function usePluginCatalog(selectedId: string | null) { busy, retryList: () => setListAttempt((attempt) => attempt + 1), retryReadme: () => setReadmeAttempt((attempt) => attempt + 1), - async install(id: string) { + async install(id: string, acceptedSourceId?: string, clearPreviousSource = false) { if (installing.current) return; installing.current = true; setBusy(true); setInstallError(null); try { const bridge = netcattyBridge.require(); if (!bridge.installCatalogPlugin) throw new Error('Catalog installation unavailable'); - await bridge.installCatalogPlugin(id, entries.find((entry) => entry.id === id)?.selectionToken); + if (clearPreviousSource && sourceBinding && sourceBinding.id !== sourceId) { + if (!bridge.resetPluginSource) throw new Error('Source reset unavailable'); + await bridge.resetPluginSource(id, sourceBinding.id); + setSourceBinding(null); + } + await bridge.installCatalogPlugin(id, entries.find((entry) => entry.id === id)?.selectionToken, sourceId, acceptedSourceId); window.dispatchEvent(new Event('netcatty:plugin-packages-changed')); } catch (cause) { if (mounted.current) setInstallError({ id, message: String(cause) }); } finally { installing.current = false; if (mounted.current) setBusy(false); } diff --git a/application/state/usePluginManager.ts b/application/state/usePluginManager.ts index 0ad4f2a27..95787f2c2 100644 --- a/application/state/usePluginManager.ts +++ b/application/state/usePluginManager.ts @@ -61,9 +61,14 @@ export function usePluginManager() { if (!bridge.setPluginEnabled) throw new Error('Plugin management unavailable'); return bridge.setPluginEnabled(id, enabled); }), - uninstall: (id: string) => run(async (bridge) => { + uninstall: (id: string, clearSource = false) => run(async (bridge) => { if (!bridge.uninstallPlugin) throw new Error('Plugin management unavailable'); - return bridge.uninstallPlugin(id); + const source = clearSource ? await bridge.getPluginSourceBinding?.(id) : null; + await bridge.uninstallPlugin(id); + if (clearSource && source) { + if (!bridge.resetPluginSource) throw new Error('Private source reset unavailable'); + await bridge.resetPluginSource(id, source.id); + } }), }; } diff --git a/application/state/usePluginSources.ts b/application/state/usePluginSources.ts new file mode 100644 index 000000000..d405c673f --- /dev/null +++ b/application/state/usePluginSources.ts @@ -0,0 +1,25 @@ +import { useCallback, useEffect, useState } from 'react'; +import { netcattyBridge } from '../../infrastructure/services/netcattyBridge'; + +export function usePluginSources() { + const [sources, setSources] = useState([]); + const [error, setError] = useState(null); + const [busy, setBusy] = useState(false); + const reload = useCallback(async () => { + const values = await netcattyBridge.require().listPluginSources?.(); + if (!values) throw new Error('Source management unavailable'); + setSources(values); + }, []); + useEffect(() => { void reload().catch((cause) => setError(String(cause))); }, [reload]); + const mutate = async (operation: () => Promise) => { + setBusy(true); setError(null); + try { await operation(); await reload(); window.dispatchEvent(new Event('netcatty:plugin-packages-changed')); return true; } + catch (cause) { setError(String(cause)); return false; } + finally { setBusy(false); } + }; + return { sources, error, busy, + add: (name: string, address: string) => mutate(async () => netcattyBridge.require().addPluginSource?.({ name, address })), + update: (source: NetcattyPluginSource, name: string, enabled: boolean) => mutate(async () => netcattyBridge.require().updatePluginSource?.({ id: source.id, name, enabled })), + remove: (id: string, disablePlugins: boolean) => mutate(async () => netcattyBridge.require().removePluginSource?.(id, disablePlugins)), + }; +} diff --git a/components/settings/tabs/PluginInfo.interaction.test.tsx b/components/settings/tabs/PluginInfo.interaction.test.tsx index 38739c8d1..ce6f6910d 100644 --- a/components/settings/tabs/PluginInfo.interaction.test.tsx +++ b/components/settings/tabs/PluginInfo.interaction.test.tsx @@ -52,7 +52,7 @@ test('information previews on hover/focus, pins on click and Escape returns focu const entry = { id: 'com.example.guide', name: 'Guide', author: 'Example', version: '1.0.0', license: 'MIT', repository: 'example/plugin', commit: 'a'.repeat(40), description: 'Synthetic metadata', manifest: { id: 'com.example.guide', name: 'Guide', publisher: 'Example', main: { browser: 'index.js' }, engines: { netcatty: '*', api: '0.1.0-internal' } }, } as NetcattyPluginCatalogEntry; - const catalog = { entries: [entry], source: 'registry', listStatus: 'ready', listError: null, readme: '# Guide', readmeStatus: 'ready', readmeError: null, error: null, busy: false, retryList() {}, retryReadme() {}, async install() {} } as ReturnType; + const catalog = { entries: [entry], source: 'registry', sourceBinding: null, listStatus: 'ready', listError: null, readme: '# Guide', readmeStatus: 'ready', readmeError: null, error: null, busy: false, retryList() {}, retryReadme() {}, async install() {} } as ReturnType; function Browser() { const [selected, setSelected] = useState(null); const [toolbar, setToolbar] = useState(null); diff --git a/components/settings/tabs/PluginMarketplace.interaction.test.tsx b/components/settings/tabs/PluginMarketplace.interaction.test.tsx index fee43c845..d6f38d467 100644 --- a/components/settings/tabs/PluginMarketplace.interaction.test.tsx +++ b/components/settings/tabs/PluginMarketplace.interaction.test.tsx @@ -28,7 +28,7 @@ const entries = ['Alpha', 'Beta'].map((name) => ({ manifest: { manifestVersion: 1, id: `com.example.${name.toLowerCase()}`, name, version: '1.0.0', publisher: 'Example', engines: { netcatty: '>=1.0.0', api: '0.1.0-internal' }, main: { browser: 'index.js' }, permissions: { required: ['settings.read'] } }, })) as NetcattyPluginCatalogEntry[]; const catalog = { - entries, source: 'registry', listStatus: 'ready', listError: null, readme: '# Author documentation', readmeStatus: 'ready', readmeError: null, + entries, source: 'registry', sourceBinding: null, listStatus: 'ready', listError: null, readme: '# Author documentation', readmeStatus: 'ready', readmeError: null, error: null, busy: false, retryList() {}, retryReadme() {}, async install() {}, } as ReturnType; @@ -42,7 +42,7 @@ test('catalog keeps search during selection/back, switches detail, and displays function Harness() { const [selected, setSelected] = useState(null); return ; + installed={[{ id: entries[0].id, activeVersion: '0.9.0', enabled: false, source: { id: 'official', kind: 'official', name: 'Official', origin: 'https://plugins.netcatty.app' }, runtime: { lastError: 'Incompatible with this host' } } as NetcattyInstalledPlugin]} />; } try { await act(async () => { renderer = create(); }); @@ -158,7 +158,21 @@ test('replacing an installed plugin discloses that its running version will stop const downloadable = { ...entries[0], artifact: { url: 'https://github.com/example/plugin/releases/download/v1/plugin.ncpkg', sha256: 'a'.repeat(64) } }; const html = renderToStaticMarkup( {}} - installed={[{ id: downloadable.id, activeVersion: '0.9.0', enabled: true } as NetcattyInstalledPlugin]} />); + installed={[{ id: downloadable.id, activeVersion: '0.9.0', enabled: true, source: { id: 'official', kind: 'official', name: 'Official', origin: 'https://plugins.netcatty.app' } } as NetcattyInstalledPlugin]} />); assert.match(html, /]*>This replaces and stops the installed version\./); assert.ok(html.indexOf('This replaces and stops') < html.indexOf('Install this version (disabled)')); }); + +test('a mirror cannot claim another source installation or offer cross-source replacement', () => { + const mirror = { id: 'third-party:mirror', kind: 'third-party' as const, name: 'Netcatty', origin: 'https://mirror.example.com' }; + const existing = { id: entries[0].id, activeVersion: '1.0.0', enabled: true, source: { id: 'official', kind: 'official', name: 'Official', origin: 'https://plugins.netcatty.app' } } as NetcattyInstalledPlugin; + const list = renderToStaticMarkup( {}} installed={[existing]} />); + assert.doesNotMatch(list, />Installed {}} installed={[existing]} />); + assert.match(detail, /installed from another source/); + assert.match(detail, /https:\/\/plugins.netcatty.app/); + assert.match(detail, /disabled=""[^>]*>Install this version/); +}); diff --git a/components/settings/tabs/PluginMarketplace.tsx b/components/settings/tabs/PluginMarketplace.tsx index 670e075c1..479f89b12 100644 --- a/components/settings/tabs/PluginMarketplace.tsx +++ b/components/settings/tabs/PluginMarketplace.tsx @@ -1,5 +1,6 @@ import { createPortal } from 'react-dom'; import { PluginStatus } from './PluginStatus'; +import { Dialog, DialogContent, DialogDescription, DialogTitle } from '../../ui/dialog'; import { PluginInfo } from './PluginInfo'; import React, { useRef, useState } from 'react'; import { PluginBrandIcon } from '../../plugins/PluginBrandIcon'; @@ -11,14 +12,15 @@ import { Button } from '../../ui/button'; import { PluginPackageDetails } from './PluginPackageManager'; import { PluginReadme } from './PluginReadme'; -export function PluginMarketplace({ installed = [], toolbarContainer, noVault }: { noVault?: boolean; installed?: NetcattyInstalledPlugin[]; toolbarContainer?: HTMLElement | null }) { +export function PluginMarketplace({ installed = [], toolbarContainer, noVault, source }: { source?: NetcattyPluginSource; noVault?: boolean; installed?: NetcattyInstalledPlugin[]; toolbarContainer?: HTMLElement | null }) { const [selected, setSelected] = useState(null); - const catalog = usePluginCatalog(selected); - return ; + const catalog = usePluginCatalog(selected, source?.id); + return ; } // The browser owns only presentation state; installation and README policy stay in the existing hook. -export function PluginMarketplaceContent({ catalog, installed, selected, onSelect, toolbarContainer, noVault }: { +export function PluginMarketplaceContent({ catalog, installed, selected, onSelect, toolbarContainer, noVault, marketSource }: { + marketSource?: NetcattyPluginSource; noVault?: boolean; toolbarContainer?: HTMLElement | null; catalog: ReturnType; @@ -28,13 +30,19 @@ export function PluginMarketplaceContent({ catalog, installed, selected, onSelec }) { const { t } = useI18n(); const [search, setSearch] = useState(''); + const [confirmInstall, setConfirmInstall] = useState(false); + const [clearPreviousSource, setClearPreviousSource] = useState(false); const listRef = useRef(null); const detailRef = useRef(null); + const installButtonRef = useRef(null); const lastSelection = useRef(null); const pageScroll = useRef(0); const entry = catalog.entries.find((item) => item.id === selected); const filtered = filterPluginCatalog(catalog.entries, search); - const installedEntry = installed.find((item) => item.id === entry?.id); + const sourceId = marketSource?.id ?? 'official'; + const sameSource = (plugin: NetcattyInstalledPlugin) => (plugin.source?.id ?? 'local') === sourceId; + const installedEntry = installed.find((item) => item.id === entry?.id && sameSource(item)); + const conflictingInstall = installed.find((item) => item.id === entry?.id && !sameSource(item)); const choose = (id: string) => { const pane = listRef.current?.closest('[data-settings-scroll-pane]'); pageScroll.current = pane?.scrollTop ?? 0; @@ -70,7 +78,7 @@ export function PluginMarketplaceContent({ catalog, installed, selected, onSelec {catalog.listStatus === 'error' &&

{catalog.listError}

} {catalog.listStatus === 'ready' && catalog.entries.length === 0 &&

{t('settings.plugins.market.empty')}

}
{filtered.map((item) => { - const isInstalled = installed.some((plugin) => plugin.id === item.id); + const isInstalled = installed.some((plugin) => plugin.id === item.id && sameSource(plugin)); return
:
{t('settings.plugins.market.sourceBadge')}{t('settings.plugins.market.sourceOnly')}
} + {conflictingInstall &&

{t('settings.plugins.sources.conflict')} {conflictingInstall.source?.origin ?? t('settings.plugins.sources.local')}

} + {entry.artifact ?

{t('settings.plugins.market.installNote')}

{catalog.listError &&

{t('settings.plugins.market.offlineShort')}

}
:
{t('settings.plugins.market.sourceBadge')}{t('settings.plugins.market.sourceOnly')}
}

{t('settings.plugins.market.manifest')}

README

{t('settings.plugins.market.readmeNote')}
{catalog.readmeStatus === 'loading' &&

{t('settings.plugins.loading')}

} {catalog.readmeStatus === 'error' &&

{catalog.readmeError}

} @@ -97,6 +106,13 @@ export function PluginMarketplaceContent({ catalog, installed, selected, onSelec
} + { event.preventDefault(); installButtonRef.current?.focus(); }}> + {t('settings.plugins.sources.installConfirm')}{t('settings.plugins.sources.risk')} +

{marketSource?.origin}

+ {entry && } + {catalog.sourceBinding && catalog.sourceBinding.id !== (marketSource?.id ?? 'official') && } + +
; } diff --git a/components/settings/tabs/PluginPackageManager.tsx b/components/settings/tabs/PluginPackageManager.tsx index 0f7f74203..a2266ffc8 100644 --- a/components/settings/tabs/PluginPackageManager.tsx +++ b/components/settings/tabs/PluginPackageManager.tsx @@ -53,6 +53,7 @@ export function PluginPackageManager({ manager, onSelectionChange }: { manager: const { t, resolvedLocale } = useI18n(); const [selected, setSelected] = useState(null); const [search, setSearch] = useState(''); + const [sourceFilter, setSourceFilter] = useState(''); const rootRef = useRef(null); const scrollTop = useRef(0); const lastSelection = useRef(null); @@ -72,11 +73,13 @@ export function PluginPackageManager({ manager, onSelectionChange }: { manager: else Array.from(rootRef.current?.querySelectorAll('[data-plugin-card]') ?? []).find((button) => button.dataset.pluginCard === lastSelection.current)?.focus({ preventScroll: true }); }); }; - const visible = selectedPlugin ? [selectedPlugin] : manager.plugins.filter((plugin) => [nameOf(plugin), plugin.manifest?.publisher, plugin.manifest?.description, plugin.id].some((value) => JSON.stringify(value ?? '').toLocaleLowerCase().includes(search.trim().toLocaleLowerCase()))); + const visible = selectedPlugin ? [selectedPlugin] : manager.plugins.filter((plugin) => (!sourceFilter || (plugin.source?.id ?? 'local') === sourceFilter) && [nameOf(plugin), plugin.manifest?.publisher, plugin.manifest?.description, plugin.id].some((value) => JSON.stringify(value ?? '').toLocaleLowerCase().includes(search.trim().toLocaleLowerCase()))); const [removing, setRemoving] = useState(null); + const [clearSource, setClearSource] = useState(false); if (!manager.available) return null; return
{selectedPlugin && } + {!selectedPlugin && manager.plugins.length > 0 && } {!selectedPlugin && manager.plugins.length > 0 && setSearch(event.target.value)} placeholder={t('settings.plugins.market.search')} aria-label={t('settings.plugins.market.search')} />} {!selectedPlugin && manager.plugins.length > 0 && visible.length === 0 &&

{t('settings.plugins.market.noResults')}

} {manager.error &&

{manager.error}

} @@ -99,6 +102,7 @@ export function PluginPackageManager({ manager, onSelectionChange }: { manager: {t(manager.statusKnown === false ? 'settings.plugins.permissions.statusUnknown' : plugin.enabled ? 'settings.plugins.manager.enabled' : 'settings.plugins.manager.disabled')} +

{t('settings.plugins.sources.source')}: {t(plugin.source?.kind === 'official' ? 'settings.plugins.sources.official' : plugin.source?.kind === 'third-party' ? 'settings.plugins.sources.thirdparty' : 'settings.plugins.sources.local')}{plugin.source?.origin ? ` · ${plugin.source.origin}` : ''}

{plugin.manifest?.publisher &&

{plugin.manifest.publisher}

}

{descriptionOf(plugin) || t('settings.plugins.manager.noDescription')}

{!selectedPlugin ?
@@ -111,9 +115,10 @@ export function PluginPackageManager({ manager, onSelectionChange }: { manager: { await manager.refresh(); }} /> {removing === plugin.id ?

{t('settings.plugins.manager.removeNote')}

- + + -
: } +
: } } )} diff --git a/components/settings/tabs/PluginThirdPartyMarket.interaction.test.tsx b/components/settings/tabs/PluginThirdPartyMarket.interaction.test.tsx new file mode 100644 index 000000000..d984d2604 --- /dev/null +++ b/components/settings/tabs/PluginThirdPartyMarket.interaction.test.tsx @@ -0,0 +1,55 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { JSDOM } from 'jsdom'; + +test('source management requires consent and Escape restores either opener inside the plugin window', async () => { + const dom = new JSDOM('
', { pretendToBeVisual: true, url: 'http://localhost' }); + const previous = new Map(); + const install = (key: string, value: unknown) => { + previous.set(key, Object.getOwnPropertyDescriptor(globalThis, key)); + Object.defineProperty(globalThis, key, { configurable: true, writable: true, value }); + }; + for (const key of ['window', 'document', 'navigator', 'HTMLElement', 'HTMLInputElement', 'Element', 'Node', 'NodeFilter', 'MutationObserver', 'CustomEvent', 'Event', 'KeyboardEvent', 'MouseEvent']) { + install(key, key === 'window' ? dom.window : dom.window[key as keyof typeof dom.window]); + } + install('getComputedStyle', dom.window.getComputedStyle.bind(dom.window)); + install('requestAnimationFrame', dom.window.requestAnimationFrame.bind(dom.window)); + install('cancelAnimationFrame', dom.window.cancelAnimationFrame.bind(dom.window)); + install('IS_REACT_ACT_ENVIRONMENT', true); + // Install a synthetic preload surface on the isolated DOM window. + Object.defineProperty(dom.window, 'netcatty', { value: { listPluginSources: async () => [] }, configurable: true }); + const { default: React, act } = await import('react'); + const { createRoot } = await import('react-dom/client'); + const { PluginThirdPartyMarket } = await import('./PluginThirdPartyMarket'); + const { PluginManagementDialog } = await import('./PluginManagementDialog'); + const { I18nProvider } = await import('../../../application/i18n/I18nProvider'); + const root = createRoot(document.getElementById('root')!); + const settle = () => new Promise((resolve) => setTimeout(resolve, 60)); + try { + await act(async () => root.render()); + await act(async () => { document.querySelector('button')!.click(); await settle(); }); + for (const label of ['Manage sources', 'Add source']) { + const opener = [...document.querySelectorAll('button')].find((button) => button.textContent === label)!; + assert.ok(opener); + await act(async () => { opener.focus(); opener.click(); await settle(); }); + assert.equal(document.querySelectorAll('[role="dialog"]').length, 2); + const dialogs = document.querySelectorAll('[role="dialog"]'); + const dialog = dialogs[dialogs.length - 1]; + assert.match(dialog.textContent ?? '', /real domain/); + assert.equal(dialog.querySelector('input[type="checkbox"]')?.checked, false); + assert.equal(dialog.querySelector('button[type="submit"]')?.disabled, true); + await act(async () => { dialog.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })); await settle(); }); + assert.equal(document.querySelectorAll('[role="dialog"]').length, 1); + assert.equal(document.activeElement, opener); + } + } finally { + // Radix schedules unmount autofocus on a timer. Drain it while the DOM's + // Event constructor is still installed (Node 22 has a distinct global Event). + await act(async () => { root.unmount(); await settle(); }); + dom.window.close(); + for (const [key, descriptor] of previous) { + if (descriptor) Object.defineProperty(globalThis, key, descriptor); + else Reflect.deleteProperty(globalThis, key); + } + } +}); diff --git a/components/settings/tabs/PluginThirdPartyMarket.tsx b/components/settings/tabs/PluginThirdPartyMarket.tsx new file mode 100644 index 000000000..23c7bde4b --- /dev/null +++ b/components/settings/tabs/PluginThirdPartyMarket.tsx @@ -0,0 +1,59 @@ +import React, { useRef, useState } from 'react'; +import { usePluginSources } from '../../../application/state/usePluginSources'; +import { useI18n } from '../../../application/i18n/I18nProvider'; +import { Button } from '../../ui/button'; +import { Input } from '../../ui/input'; +import { Dialog, DialogContent, DialogDescription, DialogTitle } from '../../ui/dialog'; +import { PluginMarketplace } from './PluginMarketplace'; + +export function PluginThirdPartyMarket({ installed, toolbarContainer, noVault }: { + installed: NetcattyInstalledPlugin[]; toolbarContainer?: HTMLElement | null; noVault?: boolean; +}) { + const { t } = useI18n(); + const model = usePluginSources(); + const [selected, setSelected] = useState(''); + const [visited, setVisited] = useState([]); + const [managing, setManaging] = useState(false); + const opener = useRef(null); + const openManager = (event: React.MouseEvent) => { opener.current = event.currentTarget; setManaging(true); }; + const [name, setName] = useState(''); + const [address, setAddress] = useState(''); + const [accepted, setAccepted] = useState(false); + const [removing, setRemoving] = useState(null); + const [disablePlugins, setDisablePlugins] = useState(false); + const sources = model.sources.filter((source) => source.kind === 'third-party'); + const source = sources.find((item) => item.id === selected && item.enabled); + let domain = ''; + try { domain = new URL(address).host; } catch { /* Host validates before saving. */ } + return
+
+ + +
+ {!source &&

{t('settings.plugins.sources.empty')}

} + {/* Keep each visited source mounted to preserve its own selection/search/scroll. */} + {sources.filter((item) => item.enabled && (item.id === selected || visited.includes(item.id))).map((item) => { + return ; + })} + { event.preventDefault(); opener.current?.focus(); }}> + {t('settings.plugins.sources.manage')}{t('settings.plugins.sources.risk')} + {model.error &&

{model.error}

} +
{sources.map((item) =>
+ { if (event.target.value !== item.name) void model.update(item, event.target.value, Boolean(item.enabled)); }} disabled={model.busy} /> +

{item.origin}

+
+ {removing === item.id &&

{t('settings.plugins.sources.removeNote')}

} +
)}
+
{ event.preventDefault(); if (accepted) void model.add(name, address).then((ok) => { if (ok) { setName(''); setAddress(''); setAccepted(false); } }); }}> + setName(event.target.value)} placeholder={t('settings.plugins.sources.name')} aria-label={t('settings.plugins.sources.name')} /> + { setAddress(event.target.value); setAccepted(false); }} placeholder="https://plugins.example.com" aria-label={t('settings.plugins.sources.address')} /> + {domain &&

{domain}

} + + +
+
+
; +} diff --git a/components/settings/tabs/SettingsPluginsTab.tsx b/components/settings/tabs/SettingsPluginsTab.tsx index 2d2d5fb0a..74977b896 100644 --- a/components/settings/tabs/SettingsPluginsTab.tsx +++ b/components/settings/tabs/SettingsPluginsTab.tsx @@ -1,3 +1,4 @@ +import { PluginThirdPartyMarket } from './PluginThirdPartyMarket'; import { usePluginManager } from '../../../application/state/usePluginManager'; import { PluginManagementDialog } from './PluginManagementDialog'; import { PluginMarketplace } from './PluginMarketplace'; @@ -289,7 +290,7 @@ function PluginManagementContent({ handoff }: { handoff: (action: () => void) => const manager = usePluginManager(); const [catalogToolbar, setCatalogToolbar] = useState(null); const [selectedInstalled, setSelectedInstalled] = useState(null); - const [pluginView, setPluginView] = useState<'installed' | 'marketplace'>('installed'); + const [pluginView, setPluginView] = useState<'installed' | 'marketplace' | 'thirdparty'>('installed'); const availableFonts = useAvailableFonts(); const scopeCatalog = usePluginSettingScopeCatalog(); const [scopeIds, setScopeIds] = useState>>({}); @@ -310,11 +311,12 @@ function PluginManagementContent({ handoff }: { handoff: (action: () => void) => return (
- { setSelectedInstalled(null); setPluginView(value as 'installed' | 'marketplace'); }} className="space-y-5"> + { setSelectedInstalled(null); setPluginView(value as 'installed' | 'marketplace' | 'thirdparty'); }} className="space-y-5">
{t('settings.plugins.manager.installed')} {manager.plugins.length} - {t('settings.plugins.market.title')} + {t('settings.plugins.sources.official')} + {t('settings.plugins.sources.thirdparty')}
{pluginView === 'installed' && } @@ -322,7 +324,8 @@ function PluginManagementContent({ handoff }: { handoff: (action: () => void) =>
- + + {contextualScopes.size > 0 && ( diff --git a/docs/plugin-platform/byte-stream-checkpoint.md b/docs/plugin-platform/byte-stream-checkpoint.md new file mode 100644 index 000000000..833ac4b37 --- /dev/null +++ b/docs/plugin-platform/byte-stream-checkpoint.md @@ -0,0 +1,111 @@ +# Byte stream integration checkpoint + +The branch starts at #3978 `91b8927c56314e68c06e2c008e84559ddfb96d78`. +It integrates source APIs from #3981 `ab8764a31752fd2d226c9d029c4d65498ba7b063` +and AI service/adapters from #3986 `264f1d983cd1ed83fe4873974a614fff2f47f989`. +No source database or sync implementation is changed by the transport delta. + +## Registered transport + +Canonical definitions are in `packages/plugin-contract/schema/plugin-contract.schema.json`. +`network.byte-streams` negotiates the capability. The separate `network.stream` +permission requires explicit `tcp://host:port` or `tls://host:port` resources. +Wildcard declarations and grants cannot authorize raw streams. HTTP grants and +payload limits are unchanged. + +The SDK exposes `context.network.connect({ endpoint }, cancellationToken?)`. +The returned connection has `endpoint`, `readable`, `writable`, `close()`, and +`dispose()`. The control methods are `network.stream.connect`, +`network.stream.attach`, and `network.stream.close`. Descriptors, request +shapes, feature names, limits, generated SDK types, and host validators share +the canonical schema. Unknown request properties are rejected. + +The registered service authenticates the host runtime before source lookup. +Runtime startup captures the existing opaque source owner. Every asynchronous +commit revalidates the runtime, active and retained source, and opaque owner +through the source task's APIs. Caller-supplied owner/source parameters are +rejected. Audit commits also verify the source binding. + +Connection and stream IDs are host-issued and bound to that runtime and owner. +The SDK prepares its incoming waiter before attach starts the host producer. +Both directions reuse the existing binary stream router and credit windows. +Input credit returns after the socket write callback. Output backpressure +bounds the producer. The router has one optional producer `onClose` hook; +peer cancellation releases the socket even while it is idle. + +The host validates all DNS answers and pins a literal IP. Production rejects +loopback, link-local, unspecified, multicast, mapped local addresses, selected +IPv6 tunnel forms, and the machine's own interface addresses. The production +host constructor never forwards the core's explicit local-test override. +There is no proxy discovery, reconnect, UDP, listen, generic IPC, shell, Node +plugin runtime, or filesystem escape. + +Limits are four connections per runtime, 64 globally, 64 KiB chunks and socket +buffer thresholds, and 8 MiB combined bytes per connection, plus the existing +runtime byte quota. Connect, idle, and lifetime deadlines are 10, 30, and 120 +seconds. Close tombstones are capped at 256 small identity records. Revocation, +runtime stop, disable, shutdown, and stream cancellation release resources. + +TLS requires trust and original-hostname validation with TLS 1.2 or later. +Plugins cannot set custom CAs, SNI, or validation exceptions. STARTTLS is not +implemented. Generic audit records contain endpoint, runtime, handle, and byte +counts. The host does not inspect SQL or record payloads or credentials. + +## Additive AI interface for the parallel owner + +The same canonical schema defines the relayed `AI_CONTEXT_ROUTES` types. +The SDK/runtime expose `context.ai.openChat/startTurn/readTurn/stopTurn/closeChat` +and `context.selectedContext.list/read`. Host registration advertises +`ai.model-invocation` and `context.selected-read`, and wires runtime cleanup, +plugin disable, revocation through the service, and shutdown. + +The trusted host adapter constructor option is `pluginAIHostAdapter`. It has +the service owner's `assertActive`, `selectModel`, `listSelected`, `reviewText`, +and optional lifecycle callbacks. These callbacks are never exposed to plugin +views. The default adapter rejects model invocation, returns no selected +resources, and refuses text review. The AI owner still owns real renderer +wiring and model/context UX. A registered synthetic adapter test is not proof +of that remaining production wiring. + +## Database example + +`examples/plugins/database-minimal` is an ordinary browser plugin. Its developer +preparation tool creates an `.ncpkg` for one exact disposable private IPv4 +endpoint. The output contains a browser bundle, a normal manifest, and view +assets. The preparation tool and its Node dependencies are not in the plugin. + +Only the example contains the database protocol: common protocol 4.1, +`mysql_native_password`, and +`SELECT value FROM plugin_demo.example_result LIMIT 1`. +The view accepts session-only fixture credentials and clears its password +field before dispatch. It does not save view state, settings, logs, or secrets. +The host never exposes SSH or AI credentials. JavaScript does not promise +memory zeroization. The account's server-side SELECT grant enforces read-only +access. The fixed query is not a SQL security classifier. + +The example has no query editor, schema browser, pool, arbitrary SQL, or host +connection-management subsystem. See the example README for native setup. + +## Evidence and limits + +- Both source-reviewed races have executable real-loopback regressions here. + Delayed final-byte consumption previously lost EOF after the socket closed. + Double-microtask cancellation previously created an untracked late socket. + Each regression failed before its respective fix and passed afterward. +- The broker tests use real TCP/TLS sockets, including trusted fixture CA, + untrusted certificate and wrong-hostname denial. Connect and idle deadline + cases use mock clocks around real sockets or delayed DNS. +- The installed entrypoint test builds and installs a normal package, executes + its actual browser entry module through SDK/RPC/binary streams, and exercises + grant denial, exact resources, unknown-field rejection, close, revoke, and + disable. It also exercises registered AI/context SDK routes with a synthetic + trusted adapter. Its runtime harness is Node and is explicitly not a browser + sandbox or OS sandbox test. +- The disposable MariaDB test checks a synthetic SELECT result and server-side + INSERT denial. It creates an internal network, publishes no host ports, and + removes the container and network. Database transport is plain TCP inside + that disposable network, not database TLS. + +Normal native BrowserWindow, full app/package checks, exact-head independent +review, and screenshot/video acceptance remain separate required evidence. +Do not disable the Chromium sandbox to obtain that evidence. diff --git a/docs/plugin-platform/market-sources.md b/docs/plugin-platform/market-sources.md new file mode 100644 index 000000000..5f15b9e89 --- /dev/null +++ b/docs/plugin-platform/market-sources.md @@ -0,0 +1,84 @@ +# Market sources (unreleased) + +The plugin manager has Installed, Official marketplace and Third-party marketplace +pages. Listing a plugin in the official market does not certify it or establish +that Netcatty maintains it. Remote manifests, publisher names, source names and +README content cannot create a host-issued official badge. This revision does not +issue maintainer badges. README text and images remain author content. + +## Add a source + +Enter a public HTTPS origin, for example `https://plugins.example.com`, or that +origin's `/v1/snapshot.json`. Names can change; identity is derived by the host +from the canonical origin. Credentials, query strings, fragments, custom ports, +IP literals and local hostnames are rejected. The initial third-party transport +requires public IPv4 DNS records, pins the checked address to the TLS connection, +and rejects private/reserved destinations. IPv6-only sources are not supported +in this revision. No cookies, login tokens, redirects or GitHub fallback are used. + +Third-party sources begin empty. A failed request never substitutes the official +catalog. Each source has its own in-memory last-known-good snapshot and selection +tokens; an offline snapshot is browse-only. A process restart requires a fresh +third-party fetch. The official source remains fixed to `plugins.netcatty.app` +and retains its bundled source examples when unavailable. + +## Publish a static source + +Use the existing snapshot protocol in the registry project's +`docs/STATIC-DISTRIBUTION.md`. Every source +serves `/v1/snapshot.json`, pointing to hash/size-bound catalog, index and delivery +JSON under `/snapshots//`. All resources remain on the source's +origin under content-addressed `/assets/` paths. Whole-JSON budgets, schema, +manifest, compatibility, browser-runtime admission and archive validation still +apply. Third-party source consent is not permission consent. + +Delivery v1 is unchanged and source-only. Delivery **v2** has the same fields and +strict schema as v1, with `schemaVersion: 2` and one extension: each plugin's +`artifact` can be null or a package reference: + +```json +{"path":"/assets/<64-lowercase-hex-sha256>.ncpkg","sha256":"","size":12345} +``` + +Packages are at most 32 MiB. The catalog entry must contain +`artifact: {url: "https://plugins.example.com/assets/.ncpkg", sha256}`. +The index's current, non-withdrawn version must exactly equal the catalog entry +and use `distribution: "release"`. Source-only entries retain null delivery +artifacts and `distribution: "source-only"`. Avatars remain null; remote README +embeds are not loaded. README and PNG/WebP references retain the v1 bounds. +Existing official bootstrap entries are not changed or made installable. + +Before every install, refresh and validate the entire snapshot again. A changed +selection, withdrawal, unavailable source, altered hash or size prevents install; +there is no fallback to another source or latest release. Packages install disabled. + +## Ownership and changing source + +A public plugin ID can have only one installed source. The package's host install +metadata and durable database binding record that source, including across +recovery and uninstall. Cross-source install or update is rejected, even when +version and package bytes match. Local imports are a separate source. + +Private settings, view state, persistent and in-memory grants, secrets, and cloud +sidecars are namespaced by host-derived source identity. KV keys are qualified +inside the existing per-plugin FK. Code, permissions and source configuration do +not participate in cloud sync. Old-source cloud settings may remain orphaned; +they cannot hydrate the same plugin ID from a different source. Generic KV still +is not cloud-synced. No host/Vault/input migration changes are made. + +To change source, uninstall and explicitly select **clear this source's private +data, grants and secrets**. The host serializes shutdown, revocation, private-file +cleanup and binding reset. This is destructive and is never selected by default. +Then install from the new source and review permissions again. An uninstall that +retains data deliberately retains the binding and continues to reject other sources. + +Removing a market keeps its installed plugins and data. Updates stop; optionally +disable its plugins. No other market silently takes over. Disabling a source only +stops browsing/install/update access; it does not silently revoke existing plugins. + +## Validation limits + +Tests use synthetic source responses and first-party packages. Passing tests is +not a sandbox certification. Native UI, real third-party hosting, network +availability and multi-device encrypted-sync acceptance must be reported +separately. No real credentials or untrusted community code are needed for tests. diff --git a/docs/plugin-platform/registry-client.md b/docs/plugin-platform/registry-client.md index 59cb52447..63f23f7e7 100644 --- a/docs/plugin-platform/registry-client.md +++ b/docs/plugin-platform/registry-client.md @@ -1,56 +1,84 @@ -# Official registry client +# Official static distribution client -The Community page refreshes the fixed endpoint -`https://raw.githubusercontent.com/binaricat/netcatty-plugins/main/catalog.json` -in the main process. The renderer cannot choose a registry URL. This endpoint -must be published separately; client implementation and synthetic tests do not -prove the repository or an online artifact is available. +Community starts at the fixed main-process endpoint +`https://plugins.netcatty.app/v1/snapshot.json`. The renderer cannot choose an +endpoint. All automatic catalog, README and potential package reads allow only +that exact HTTPS origin: no credentials, query, fragment, noncanonical URL or +redirect. No GitHub API/raw/avatar/release fallback exists. Explicit user-opened +source links may still open GitHub in an external browser. -## Catalog contract +## Snapshot contract -`catalog.json` is an array of at most 1,000 current entries. Each entry supplies -`id`, `version`, `name`, `description`, `author`, `repository` (`owner/repository`), -`commit` (full 40-character SHA), `license`, `readme` (relative Markdown path), -and `manifest`. Optional `artifact` contains `url` and SHA-256 `sha256`. -Unknown catalog-entry and artifact fields are rejected. The whole JSON value, -including manifest defaults, uses the existing 128-level / 100,000-value budget -and finite-number validation. The existing manifest schema, browser-only distribution policy, identity/version -and license checks apply. Source-only entries remain build-and-import examples. -No download counts, ratings, or timestamps are invented. Brand previews remain -bundled and reviewed; arbitrary author image URLs are never loaded. +This client implements the version-1 contract from +`binaricat/netcatty-plugins@7bfe23e5627e16ba63806de6dded5b2667c02984`. +The source catalog/index remain unchanged; **no `readmeAsset` field is added**. -Reads are anonymous HTTPS, redirect-free for the registry, bounded to 2 MiB, -and time out after 30 seconds. All entries must validate, safely clone, and generate every selection token before -atomically replacing the current snapshot. Invalid JSON/schema, network failure, and oversized responses -leave the previous good snapshot intact. Errors and Retry remain visible. The Community header also has Refresh, including -when the last refresh succeeded; it is disabled while a request is pending. -The last good catalog is retained **in memory for this application session**; -a fresh offline launch uses bundled examples. There is no new disk cache, -database migration, cloud sync record, or credential requirement. +The pointer contains `schemaVersion: 1`, `registryCommit`, `snapshotId`, and +`catalog`, `index`, `delivery` references, each `{path, sha256, size}`. Paths must +be `/snapshots//.json`; `snapshotId` equals the raw delivery +SHA-256. The host checks the pointer before requesting its three documents, +then checks raw byte counts/hashes, JSON budgets, schemas and cross-document +identity. The three documents must all validate before replacing any cache. -## Selection and installation +Delivery contains `schemaVersion`, `registryCommit`, `catalogSha256`, +`indexSha256`, `sourceLockSha256`, `builderSha256` and `plugins`. Each item matches +one exact catalog `id/version/repository/commit` tuple and supplies `readme`, +`iconLight`, `iconDark`, `avatar`, `artifact`. Asset references are +`{path, sha256, size}`, with `/assets/.md` for README and `.png`/`.webp` +for brand icons. This v1 publishing schema requires **avatar and artifact to +be null**. The client rejects unsupported delivery metadata rather than +inventing installable packages or deriving a GitHub avatar URL. -Each returned entry has a host-generated `selectionToken` covering its complete -JSON contents. This is a concurrency check, **not a signature or trust proof**. -README requests must still match that selection and fetch its pinned source -commit. A changed entry requires refresh and renewed review. +Index is validated with its pinned schema. Plugin/version identities must be +unique; each catalog entry must exactly equal the index's current, non-withdrawn, +source-only entry. Withdrawal does not disable, uninstall or delete any existing +plugin: this is catalog admission, not a remote installed-code kill switch. -A manual install must first refresh the official catalog successfully and match -the selected token again. Failed refresh is browse-only, even if the cached -entry has an artifact. Withdrawal, version changes, permission changes, README -changes, or artifact hash changes cannot silently replace the selected package. -Archive download then uses the existing approved-host, size, exact SHA-256, -manifest and package validation pipeline. Installation leaves the plugin disabled; -existing authorization gates still apply on activation/use. +Schemas are vendored under `electron/plugins/distribution/`, with provenance and +fixtures described there. All schema references resolve locally; schema validation +does not fetch GitHub or netcatty.com. -`index.json` release history and withdrawal records are not consumed by this -first client. Removing an entry does **not** disable, uninstall, update, or delete -data from an already installed plugin. There are no background code updates. +## Bounds, cache and selection -## Verification boundary +Pointer reads are bounded to 16 KiB, each JSON document to 2 MiB, and each README +to 256 KiB. Reads time out after 30 seconds. Whole JSON values retain the existing +128-level / 100,000-value / finite-number boundary. Catalogs contain at most 1,000 +entries. Existing manifest identity, license and browser-only policies remain. -Service regressions use synthetic network responses and package bytes; the -existing package manager tests cover archive admission. No third-party plugin, -real credential, real sync account, or live registry write is used. Native QA -must separately verify the visible offline/retry state and eventual real catalog -availability once the repository is published. +The host prepares private entries, private delivery resources and all public +selection tokens before one synchronous cache publication. Parse, integrity, +schema, clone, tuple or network failures preserve the last complete good snapshot. +The cache remains **in memory for this app session**; a fresh offline launch lists +bundled examples. No new disk database, sync record or credential is introduced. + +A host-generated selection token binds the complete entry and its delivery item. +This prevents silent selection changes; it is **not a signature**. README requests +capture the matched static reference and verify its exact byte count and digest. +Missing/offline snapshots show an error/Retry; they never synthesize a raw GitHub URL. +README HTML and remote images remain inert in the existing safe renderer. + +The current v1 distribution cannot install packages. A later publishing/client +schema revision must jointly introduce reviewed package mirroring, keep source +manifest/hash admission, and recheck the current pointer and fresh root withdrawal +ledger before any install. A historical snapshot alone cannot establish availability. +The existing lower-level package downloader accepts only official static URLs and +exact SHA-256 bytes; it does not relax those future gates or auto-enable code. + +## Network inventory + +| Path | Automatic source | Failure behavior | +| --- | --- | --- | +| Pointer / manual refresh | Fixed `/v1/snapshot.json` | Complete session cache, or bundled source-only entries | +| Catalog/index/delivery | Pointer-bound same-origin immutable paths | Reject partial or mixed snapshots | +| README details | Exact delivery `/assets/.md` | Visible error/Retry, no upstream fallback | +| Uninstalled brand icons | Existing reviewed bundled previews | Default icon; delivery icon metadata validated but not fetched by UI | +| Installed brand icons | Host-owned local package decoder | Default icon; no activation/network request | +| Author avatars | Not implemented; delivery v1 requires null | Existing local presentation; no avatar lookup | +| Package artifacts | Not published or admitted by delivery v1 | Source-only; no download action fabricated | +| Source/README links | Explicit user-opened external HTTPS link | May open GitHub; no background dependency | + +The real PR3 bootstrap is retained as a test fixture with its original bytes and +hashes. Tests also verify its brand-icon asset bytes; this does not claim a new +remote icon renderer. The static publisher is not a proxy. Client tests do not +prove deployment, mainland reachability or successful native CDN access. Native +QA must independently verify the published endpoint and visible failure state. diff --git a/electron/plugins/browserPluginRuntime.cjs b/electron/plugins/browserPluginRuntime.cjs index d65151cee..458a85c6a 100644 --- a/electron/plugins/browserPluginRuntime.cjs +++ b/electron/plugins/browserPluginRuntime.cjs @@ -288,9 +288,9 @@ class BrowserPluginRuntime { this.router.notify(method, params); } - openStream(streamId, windowBytes) { + openStream(streamId, windowBytes, options) { if (!this.router) return Promise.reject(new Error("Plugin browser runtime is not connected")); - return this.router.streams.openOutgoing(streamId, windowBytes); + return this.router.streams.openOutgoing(streamId, windowBytes, options); } getProcessId() { diff --git a/electron/plugins/byteStreamBroker.cjs b/electron/plugins/byteStreamBroker.cjs new file mode 100644 index 000000000..7e84514e9 --- /dev/null +++ b/electron/plugins/byteStreamBroker.cjs @@ -0,0 +1,297 @@ +"use strict"; + +// Host-only transport core. No protocol, credential lookup, or plugin-supplied +// Node runs here. The registered service authenticates source-bound runtimes. +const net = require("node:net"); +const tls = require("node:tls"); +const dns = require("node:dns/promises"); +const { randomUUID } = require("node:crypto"); +const { PluginRpcError, RPC_ERRORS, raceWithAbort } = require("./rpcRouter.cjs"); + +const LIMITS = Object.freeze(require("./generated/plugin-contract.schema.json").$defs.ByteStreamLimits.const); +const { canonicalizeStreamEndpoint, isLocalControlAddress } = require("./byteStreamEndpoint.cjs"); + +function failure(code, message) { return new PluginRpcError(RPC_ERRORS[code], message); } + +class PluginByteStreamBroker { + constructor(options) { + this.permissionEngine = options.permissionEngine; + this.quotaManager = options.quotaManager; + this.audit = options.audit ?? (() => {}); + this.lookup = options.lookup ?? dns.lookup; + this.connectSocket = options.connectSocket ?? ((params) => net.createConnection(params)); + this.connectTls = options.connectTls ?? ((params) => tls.connect(params)); + // Only a host test harness can opt a specific loopback endpoint in. The + // production default excludes all loopback/link-local control surfaces. + this.testLocalEndpoints = new Set(options.testLocalEndpoints ?? []); + this.isControlEndpoint = options.isControlEndpoint ?? (() => false); + this.connections = new Map(); + this.closeListeners = new Set(); + this.closed = false; + this.revocation = this.permissionEngine.onDidRevoke((event) => { + for (const state of this.connections.values()) { + if (state.pluginId === event.pluginId + && (event.permission === undefined || event.permission === "network.stream") + && (event.resource === undefined || event.resource === state.endpoint)) { + this.finish(state, failure("permissionDenied", "Byte stream permission was revoked")); + } + } + }); + } + + record(state, operation) { + // Audit only host-observed generic operations, never bytes or peer messages. + try { this.audit(state.pluginId, `network.stream.${operation}`, { + runtimeId: state.runtimeId, endpoint: state.endpoint, + handleId: state.id, bytesRead: state.bytesRead, bytesWritten: state.bytesWritten, + }, state); } catch { /* An audit sink cannot keep a revoked socket alive. */ } + } + + finish(state, reason) { + if (state.closed) return; + state.closed = true; + clearTimeout(state.connectTimer); + clearTimeout(state.idleTimer); + clearTimeout(state.lifetimeTimer); + state.error = reason; + this.connections.delete(state.id); + state.controller.abort(reason ?? failure("cancelled", "Byte stream closed")); + state.socket?.destroy(); + this.record(state, "close"); + for (const listener of this.closeListeners) { + try { listener(state, reason); } catch {} + } + } + + onDidClose(listener) { + this.closeListeners.add(listener); + return { dispose: () => this.closeListeners.delete(listener) }; + } + + touch(state) { + clearTimeout(state.idleTimer); + state.idleTimer = setTimeout(() => this.finish(state, + failure("deadlineExceeded", "Byte stream idle timeout")), LIMITS.idleMs); + state.idleTimer.unref?.(); + } + + async active(state, context) { + this.assertCommit(state, context); + await context.assertActive(); + this.assertCommit(state, context); + } + + assertCommit(state, context) { + if (this.closed || state.closed || this.connections.get(state.id) !== state) { + throw state.error ?? failure("unavailable", "Byte stream is closed"); + } + state.controller.signal.throwIfAborted(); + context.signal?.throwIfAborted(); + context.assertCommit?.(); + } + + async connect(endpoint, context) { + let target; + try { target = canonicalizeStreamEndpoint(endpoint); } + catch { throw failure("invalidArgument", "Byte stream endpoint is invalid"); } + if (this.closed) throw failure("unavailable", "Byte stream broker stopped"); + if (!context.runtimeId || !context.pluginId || typeof context.assertActive !== "function") { + throw failure("unauthenticated", "Byte streams require a host runtime identity"); + } + const count = [...this.connections.values()].filter((state) => state.runtimeId === context.runtimeId).length; + if (count >= LIMITS.connectionsPerRuntime || this.connections.size >= LIMITS.connectionsTotal) { + throw failure("resourceExhausted", "Byte stream connection limit exceeded"); + } + const state = { + ...target, id: randomUUID(), pluginId: context.pluginId, runtimeId: context.runtimeId, + controller: new AbortController(), bytesRead: 0, bytesWritten: 0, + sourceOwner: context.sourceOwner, sourceId: context.sourceId, + closed: false, reading: false, writing: false, socket: null, + }; + this.connections.set(state.id, state); + const onAbort = () => this.finish(state, failure("cancelled", "Byte stream connection cancelled")); + context.signal?.addEventListener("abort", onAbort, { once: true }); + try { + await this.active(state, context); + this.assertCommit(state, context); + await raceWithAbort(Promise.resolve(this.permissionEngine.authorize({ ...context, signal: state.controller.signal }, { + permission: "network.stream", resources: [target.endpoint], + reason: `Open byte stream to ${target.endpoint}`, + operationId: `network.stream:${target.endpoint}`, + validateBeforeGrant: () => this.assertCommit(state, context), + })), state.controller.signal); + await this.active(state, context); + state.connectTimer = setTimeout(() => this.finish(state, + failure("deadlineExceeded", "Byte stream connect timeout")), LIMITS.connectMs); + const addresses = net.isIP(target.host) + ? [{ address: target.host, family: net.isIP(target.host) }] + : await raceWithAbort(Promise.resolve(this.lookup(target.host, { all: true, verbatim: true })), state.controller.signal); + await this.active(state, context); + if (!Array.isArray(addresses) || addresses.length === 0 || addresses.length > 64) { + throw failure("unavailable", "Byte stream hostname could not be resolved"); + } + // Validate the whole DNS answer and pin one literal address. No second + // lookup, redirect, proxy discovery, or reconnect can change the peer. + for (const peer of addresses) { + if (![4, 6].includes(peer.family) || net.isIP(peer.address) !== peer.family) { + throw failure("unavailable", "Byte stream resolver returned an invalid address"); + } + const local = isLocalControlAddress(peer.address); + const allowedTestPeer = this.testLocalEndpoints.has(target.endpoint) + && !this.isControlEndpoint(peer.address, target.port); + if ((local && !allowedTestPeer) || (!local && this.isControlEndpoint(peer.address, target.port))) { + throw failure("permissionDenied", "Byte streams cannot reach local or application control endpoints"); + } + } + const peer = addresses[0]; + const params = { + host: peer.address, port: target.port, family: peer.family, + highWaterMark: LIMITS.bufferBytes, + }; + if (target.transport === "tls") { + Object.assign(params, { + rejectUnauthorized: true, minVersion: "TLSv1.2", + ...(net.isIP(target.host) ? {} : { servername: target.host }), + checkServerIdentity: (_name, certificate) => tls.checkServerIdentity(target.host, certificate), + }); + } + this.assertCommit(state, context); + const socket = target.transport === "tls" ? this.connectTls(params) : this.connectSocket(params); + state.socket = socket; + if (state.closed) { socket.destroy(); throw state.error ?? failure("cancelled", "Byte stream connection cancelled"); } + socket.on("error", () => this.finish(state, failure("unavailable", "Byte stream transport failed"))); + // Preserve one EOF observation for a delayed consumer. This reservation + // still counts toward quotas and expires on the existing idle/life timer. + socket.on("close", () => { + if (!state.eof) this.finish(state, failure("unavailable", "Byte stream transport closed")); + }); + socket.on("end", () => { state.eof = true; }); + socket.pause(); + await raceWithAbort(new Promise((resolve) => socket.once( + target.transport === "tls" ? "secureConnect" : "connect", resolve, + )), state.controller.signal); + await this.active(state, context); + if (target.transport === "tls" && !socket.authorized) { + throw failure("permissionDenied", "Byte stream TLS validation failed"); + } + clearTimeout(state.connectTimer); + state.lifetimeTimer = setTimeout(() => this.finish(state, + failure("deadlineExceeded", "Byte stream lifetime exceeded")), LIMITS.lifetimeMs); + state.lifetimeTimer.unref?.(); + this.touch(state); + this.assertCommit(state, context); + this.record(state, "open"); + return Object.freeze({ handleId: state.id, endpoint: state.endpoint }); + } catch (error) { + this.finish(state, error); + throw error; + } finally { + context.signal?.removeEventListener("abort", onAbort); + } + } + + get(id, context) { + const state = this.connections.get(id); + if (!state || state.pluginId !== context.pluginId || state.runtimeId !== context.runtimeId + || state.sourceOwner !== context.sourceOwner || state.sourceId !== context.sourceId) { + throw failure("permissionDenied", "Byte stream handle does not belong to this runtime"); + } + return state; + } + + charge(state, direction, size) { + if (state.bytesRead + state.bytesWritten + size > LIMITS.connectionBytes) { + throw failure("resourceExhausted", "Byte stream byte limit exceeded"); + } + this.quotaManager?.chargeBytes(state.runtimeId, "network.stream", size); + state[direction] += size; + this.touch(state); + } + + async read(id, context) { + const state = this.get(id, context); + if (state.reading) throw failure("failedPrecondition", "Byte stream has a pending read"); + state.reading = true; + const onAbort = () => this.finish(state, failure("cancelled", "Byte stream read cancelled")); + context.signal?.addEventListener("abort", onAbort, { once: true }); + try { + await this.active(state, context); + while (true) { + this.assertCommit(state, context); + const available = state.socket.readableLength; + const bytes = state.socket.read(Math.min(available || LIMITS.chunkBytes, LIMITS.chunkBytes)); + if (bytes !== null) { + this.charge(state, "bytesRead", bytes.byteLength); + await this.active(state, context); + this.assertCommit(state, context); + return new Uint8Array(bytes); + } + if (state.eof || state.socket.readableEnded) { this.finish(state); return null; } + await raceWithAbort(new Promise((resolve) => { + const readable = () => { + state.socket.off("end", readable); + state.socket.off("readable", readable); + state.controller.signal.removeEventListener("abort", readable); + resolve(); + }; + state.socket.once("readable", readable); + state.socket.once("end", readable); + // Remove listeners even when cancellation wins the race. + state.controller.signal.addEventListener("abort", readable, { once: true }); + }), state.controller.signal); + await this.active(state, context); + } + } catch (error) { + this.finish(state, error); + throw error; + } finally { + context.signal?.removeEventListener("abort", onAbort); + state.reading = false; + } + } + + async write(id, bytes, context) { + const state = this.get(id, context); + if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > LIMITS.chunkBytes) { + throw failure("invalidArgument", "Byte stream chunk size is invalid"); + } + if (state.writing) throw failure("resourceExhausted", "Byte stream has a pending write"); + state.writing = true; + const onAbort = () => this.finish(state, failure("cancelled", "Byte stream write cancelled")); + context.signal?.addEventListener("abort", onAbort, { once: true }); + try { + await this.active(state, context); + this.assertCommit(state, context); + this.charge(state, "bytesWritten", bytes.byteLength); + const owned = Buffer.from(bytes); + await raceWithAbort(new Promise((resolve, reject) => { + state.socket.write(owned, (error) => error ? reject(error) : resolve()); + }), state.controller.signal); + await this.active(state, context); + } catch (error) { + this.finish(state, error); + throw error; + } finally { + context.signal?.removeEventListener("abort", onAbort); + state.writing = false; + } + } + + close(id, context) { this.finish(this.get(id, context)); } + + releaseRuntime(runtimeId) { + for (const state of this.connections.values()) { + if (state.runtimeId === runtimeId) this.finish(state, + failure("unavailable", "Byte stream runtime stopped")); + } + } + + shutdown() { + this.closed = true; + for (const state of this.connections.values()) this.finish(state, + failure("unavailable", "Byte stream broker stopped")); + this.revocation.dispose(); + } +} + +module.exports = { LIMITS, PluginByteStreamBroker, canonicalizeStreamEndpoint, isLocalControlAddress }; diff --git a/electron/plugins/byteStreamBroker.test.cjs b/electron/plugins/byteStreamBroker.test.cjs new file mode 100644 index 000000000..131d6fb96 --- /dev/null +++ b/electron/plugins/byteStreamBroker.test.cjs @@ -0,0 +1,330 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const { test } = require("node:test"); +const net = require("node:net"); +const tls = require("node:tls"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const { execFileSync } = require("node:child_process"); +const { once } = require("node:events"); +const { LIMITS, PluginByteStreamBroker, canonicalizeStreamEndpoint, isLocalControlAddress } = require("./byteStreamBroker.cjs"); +const { RPC_ERRORS } = require("./rpcRouter.cjs"); + +function context(runtimeId = "runtime-a", controller = new AbortController()) { + return { pluginId: "test.stream", runtimeId, signal: controller.signal, + assertActive: async () => controller.signal.throwIfAborted() }; +} + +async function server(t, listener, options) { + const sockets = new Set(); + const instance = options ? tls.createServer(options, listener) : net.createServer(listener); + instance.on("connection", (socket) => { + sockets.add(socket); + socket.on("error", () => {}); + socket.on("close", () => sockets.delete(socket)); + }); + instance.on("tlsClientError", () => {}); + instance.listen(0, "127.0.0.1"); + await once(instance, "listening"); + t.after(async () => { + for (const socket of sockets) socket.destroy(); + await new Promise((resolve) => instance.close(resolve)); + }); + return instance; +} + +function broker(t, endpoint, options = {}) { + const audit = []; + const requests = []; + let revoke; + const instance = new PluginByteStreamBroker({ + permissionEngine: { + authorize: async (_ctx, request) => requests.push(request), + onDidRevoke(listener) { revoke = listener; return { dispose() {} }; }, + }, + audit: (...args) => audit.push(args), + testLocalEndpoints: endpoint ? [endpoint] : [], + ...options, + }); + t.after(() => instance.shutdown()); + return { instance, requests, audit, revoke: (event) => revoke(event) }; +} + +test("stream endpoint canonicalization requires one exact host, transport and port", () => { + assert.equal(canonicalizeStreamEndpoint("tls://EXAMPLE.test:443").endpoint, "tls://example.test:443"); + assert.equal(canonicalizeStreamEndpoint("tcp://[0:0:0:0:0:0:0:1]:3306").endpoint, "tcp://[::1]:3306"); + for (const value of ["*", "tcp://*:3306", "tcp://x:0", "tcp://x:01", "tcp://x:65536", "udp://x:22", + "tcp://x", "tcp://x:22/", "tcp://user@x:22", "tcp://127.1:22", "tcp://x:22?x", "tcp://x.:22", + "tcp://[::1%25lo]:22", "tcp://x:22#x", "tcp://-x:22"]) { + assert.throws(() => canonicalizeStreamEndpoint(value), TypeError, value); + } +}); + +test("local/control address classification handles mapped IPv6 and alternate literals", () => { + for (const address of ["127.0.0.1", "127.9.8.7", "0.0.0.0", "169.254.169.254", "224.0.0.1", + "::1", "::", "::ffff:127.0.0.1", "::ffff:7f00:1", "fe80::1", "ff02::1", "2002:7f00:1::"]) { + assert.equal(isLocalControlAddress(address), true, address); + } + for (const address of ["192.168.1.2", "10.0.0.8", "203.0.113.1", "2001:db8::1", "fd00::1"]) { + assert.equal(isLocalControlAddress(address), false, address); + } +}); + +test("real TCP transport exchanges binary bytes and records no payloads", async (t) => { + const peer = await server(t, (socket) => socket.on("data", (bytes) => socket.write(bytes))); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance, requests, audit } = broker(t, endpoint); + const ctx = context(); + const handle = await instance.connect(endpoint, ctx); + const bytes = Uint8Array.from([0, 255, 1, 254, 19]); + await instance.write(handle.handleId, bytes, ctx); + assert.deepEqual(await instance.read(handle.handleId, ctx), bytes); + instance.close(handle.handleId, ctx); + assert.equal(instance.connections.size, 0); + assert.deepEqual(requests[0].resources, [endpoint]); + assert.equal(requests[0].permission, "network.stream"); + assert.deepEqual(audit.map((entry) => entry[1]), ["network.stream.open", "network.stream.close"]); + assert.equal(audit[1][2].bytesRead, bytes.byteLength); + assert.equal(audit[1][2].bytesWritten, bytes.byteLength); + assert.equal(JSON.stringify(audit).includes("data"), false); +}); + +test("remote EOF returns the final bytes and releases the connection", async (t) => { + const peer = await server(t, (socket) => socket.end("synthetic final bytes")); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance } = broker(t, endpoint); + const ctx = context(); + const { handleId } = await instance.connect(endpoint, ctx); + const chunks = []; + while (true) { + const chunk = await instance.read(handleId, ctx); + if (chunk === null) break; + chunks.push(Buffer.from(chunk)); + } + assert.equal(Buffer.concat(chunks).toString(), "synthetic final bytes"); + assert.equal(instance.connections.size, 0); +}); + +test("a delayed consumer can observe EOF after the real socket has closed", async (t) => { + const peer = await server(t, (socket) => socket.end("final")); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance, revoke } = broker(t, endpoint); + const ctx = context(); + const { handleId } = await instance.connect(endpoint, ctx); + const socket = instance.connections.get(handleId).socket; + const closed = once(socket, "close"); + assert.equal(Buffer.from(await instance.read(handleId, ctx)).toString(), "final"); + await closed; + await assert.rejects(instance.read(handleId, context("other-runtime")), { code: RPC_ERRORS.permissionDenied }); + assert.equal(await instance.read(handleId, ctx), null); + assert.equal(instance.connections.size, 0); + const second = await instance.connect(endpoint, ctx); + const secondClosed = once(instance.connections.get(second.handleId).socket, "close"); + await instance.read(second.handleId, ctx); + await secondClosed; + revoke({ pluginId: ctx.pluginId, permission: "network.stream", resource: endpoint }); + await assert.rejects(instance.read(second.handleId, ctx), { code: RPC_ERRORS.permissionDenied }); +}); + +test("denial happens before DNS or a socket is created", async (t) => { + let lookedUp = false; + const { instance } = broker(t, null, { + permissionEngine: { authorize: async () => { throw new Error("denied"); }, onDidRevoke: () => ({ dispose() {} }) }, + lookup: () => { lookedUp = true; }, + }); + await assert.rejects(instance.connect("tcp://example.test:22", context()), /denied/u); + assert.equal(lookedUp, false); + assert.equal(instance.connections.size, 0); +}); + +test("production rejects loopback, mixed DNS answers, and app control peers", async (t) => { + const endpoint = "tcp://example.test:22"; + const { instance } = broker(t, null, { + lookup: async () => [{ address: "203.0.113.1", family: 4 }, { address: "127.0.0.1", family: 4 }], + }); + await assert.rejects(instance.connect(endpoint, context()), { code: RPC_ERRORS.permissionDenied }); + await assert.rejects(instance.connect("tcp://127.0.0.1:22", context()), { code: RPC_ERRORS.permissionDenied }); + const protectedBroker = broker(t, "tcp://127.0.0.1:22", { isControlEndpoint: () => true }).instance; + await assert.rejects(protectedBroker.connect("tcp://127.0.0.1:22", context()), { code: RPC_ERRORS.permissionDenied }); +}); + +test("runtime handles cannot cross runtime or plugin boundaries", async (t) => { + const peer = await server(t, () => {}); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance } = broker(t, endpoint); + const ctx = context(); + const { handleId } = await instance.connect(endpoint, ctx); + for (const other of [context("runtime-b"), { ...ctx, pluginId: "test.other" }]) { + await assert.rejects(instance.read(handleId, other), { code: RPC_ERRORS.permissionDenied }); + assert.throws(() => instance.close(handleId, other), { code: RPC_ERRORS.permissionDenied }); + } + instance.close(handleId, ctx); + await assert.rejects(instance.write(handleId, Uint8Array.of(1), ctx), { code: RPC_ERRORS.permissionDenied }); +}); + +test("revocation and runtime release cancel pending real reads", async (t) => { + const peer = await server(t, () => {}); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance, revoke } = broker(t, endpoint); + const ctx = context(); + let handle = await instance.connect(endpoint, ctx); + const reading = instance.read(handle.handleId, ctx); + await new Promise((resolve) => setImmediate(resolve)); + revoke({ pluginId: ctx.pluginId, permission: "network.stream", resource: endpoint }); + await assert.rejects(reading, { code: RPC_ERRORS.permissionDenied }); + assert.equal(instance.connections.size, 0); + handle = await instance.connect(endpoint, ctx); + const secondRead = instance.read(handle.handleId, ctx); + instance.releaseRuntime(ctx.runtimeId); + await assert.rejects(secondRead, { code: RPC_ERRORS.unavailable }); + assert.equal(instance.connections.size, 0); +}); + +test("cancellation during DNS rejects promptly and ignores late resolution", async (t) => { + let resolveDns; + let dialed = false; + const { instance } = broker(t, null, { + lookup: () => new Promise((resolve) => { resolveDns = resolve; }), + connectSocket: () => { dialed = true; }, + }); + const controller = new AbortController(); + const pending = instance.connect("tcp://example.test:22", context("runtime-a", controller)); + await new Promise((resolve) => setImmediate(resolve)); + controller.abort(); + await assert.rejects(pending, { code: RPC_ERRORS.cancelled }); + resolveDns([{ address: "203.0.113.1", family: 4 }]); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(dialed, false); + assert.equal(instance.connections.size, 0); +}); + +test("cancellation after the last async guard cannot create a late real socket", async (t) => { + const peer = await server(t, () => {}); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + let dialed = false; + const { instance } = broker(t, endpoint, { connectSocket(options) { + dialed = true; + const socket = net.createConnection(options); + t.after(() => socket.destroy()); + return socket; + } }); + const controller = new AbortController(); + let guards = 0; + const ctx = context("runtime-a", controller); + ctx.assertActive = async () => { + controller.signal.throwIfAborted(); + if (++guards === 3) queueMicrotask(() => queueMicrotask(() => controller.abort())); + }; + await assert.rejects(instance.connect(endpoint, ctx), { code: RPC_ERRORS.cancelled }); + assert.equal(dialed, false); + assert.equal(instance.connections.size, 0); +}); + +test("connect and idle deadlines close resources and reject pending operations", async (t) => { + const peer = await server(t, () => {}); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance } = broker(t, endpoint); + t.mock.timers.enable({ apis: ["setTimeout"] }); + const ctx = context(); + const { handleId } = await instance.connect(endpoint, ctx); + const reading = instance.read(handleId, ctx); + await new Promise((resolve) => setImmediate(resolve)); + t.mock.timers.tick(LIMITS.idleMs); + await assert.rejects(reading, { code: RPC_ERRORS.deadlineExceeded }); + assert.equal(instance.connections.size, 0); + let resolveDns; + let dialed = false; + const slow = broker(t, null, { + lookup: () => new Promise((resolve) => { resolveDns = resolve; }), + connectSocket: () => { dialed = true; }, + }).instance; + const pending = slow.connect("tcp://example.test:22", ctx); + await new Promise((resolve) => setImmediate(resolve)); + t.mock.timers.tick(LIMITS.connectMs); + await assert.rejects(pending, { code: RPC_ERRORS.deadlineExceeded }); + resolveDns([{ address: "203.0.113.1", family: 4 }]); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(dialed, false); + assert.equal(slow.connections.size, 0); +}); + +test("concurrent operations and oversized writes cannot grow an unbounded queue", async (t) => { + const peer = await server(t, () => {}); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance } = broker(t, endpoint); + const ctx = context(); + const { handleId } = await instance.connect(endpoint, ctx); + const pending = instance.read(handleId, ctx); + await assert.rejects(instance.read(handleId, ctx), { code: RPC_ERRORS.failedPrecondition }); + await assert.rejects(instance.write(handleId, new Uint8Array(LIMITS.chunkBytes + 1), ctx), { code: RPC_ERRORS.invalidArgument }); + const writing = instance.write(handleId, Uint8Array.of(1), ctx); + await assert.rejects(instance.write(handleId, Uint8Array.of(2), ctx), { code: RPC_ERRORS.resourceExhausted }); + await writing; + instance.close(handleId, ctx); + await assert.rejects(pending, { code: RPC_ERRORS.cancelled }); +}); + +test("connection reservations bound concurrent DNS operations", async (t) => { + const { instance } = broker(t, null, { lookup: () => new Promise(() => {}) }); + const ctx = context(); + const pending = Array.from({ length: LIMITS.connectionsPerRuntime }, () => instance.connect("tcp://example.test:22", ctx)); + const results = Promise.allSettled(pending); + await assert.rejects(instance.connect("tcp://example.test:22", ctx), { code: RPC_ERRORS.resourceExhausted }); + instance.releaseRuntime(ctx.runtimeId); + assert.ok((await results).every((result) => result.status === "rejected")); + assert.equal(instance.connections.size, 0); +}); + +test("real unread TCP output stays bounded and byte quota closes the socket", async (t) => { + const peer = await server(t, (socket) => { + const flood = () => { while (!socket.destroyed && socket.write(Buffer.alloc(LIMITS.chunkBytes))) {} }; + socket.on("drain", flood); + flood(); + }); + const endpoint = `tcp://127.0.0.1:${peer.address().port}`; + const { instance } = broker(t, endpoint, { quotaManager: { + chargeBytes() { throw new Error("quota reached"); }, + } }); + const ctx = context(); + const { handleId } = await instance.connect(endpoint, ctx); + await new Promise((resolve) => setTimeout(resolve, 30)); + const state = instance.connections.get(handleId); + assert.ok(state.socket.readableLength <= LIMITS.bufferBytes + LIMITS.chunkBytes); + await assert.rejects(instance.read(handleId, ctx), /quota reached/u); + assert.equal(instance.connections.size, 0); +}); + +test("real TLS validates trust and the original hostname against a pinned IP", async (t) => { + const directory = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-stream-tls-test-")); + t.after(() => fs.rmSync(directory, { recursive: true, force: true })); + const keyPath = path.join(directory, "test.key"); + const certPath = path.join(directory, "test.crt"); + execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", keyPath, + "-out", certPath, "-days", "1", "-subj", "/CN=stream-fixture.test", "-addext", "subjectAltName=DNS:stream-fixture.test"], + { stdio: "ignore" }); + const cert = fs.readFileSync(certPath); + const peer = await server(t, (socket) => socket.on("data", (data) => socket.write(data)), { + key: fs.readFileSync(keyPath), cert, + }); + const endpoint = `tls://stream-fixture.test:${peer.address().port}`; + const lookup = async () => [{ address: "127.0.0.1", family: 4 }]; + const untrusted = broker(t, endpoint, { lookup }).instance; + await assert.rejects(untrusted.connect(endpoint, context()), { code: RPC_ERRORS.unavailable }); + let dialOptions; + const trusted = broker(t, endpoint, { lookup, + connectTls: (options) => { dialOptions = options; return tls.connect({ ...options, ca: cert }); }, + }).instance; + const ctx = context(); + const { handleId } = await trusted.connect(endpoint, ctx); + assert.equal(dialOptions.host, "127.0.0.1"); + assert.equal(dialOptions.servername, "stream-fixture.test"); + assert.equal(dialOptions.rejectUnauthorized, true); + await trusted.write(handleId, Uint8Array.of(42), ctx); + assert.deepEqual(await trusted.read(handleId, ctx), Uint8Array.of(42)); + trusted.close(handleId, ctx); + const wrongEndpoint = `tls://wrong-fixture.test:${peer.address().port}`; + const wrong = broker(t, wrongEndpoint, { lookup, connectTls: (options) => tls.connect({ ...options, ca: cert }) }).instance; + await assert.rejects(wrong.connect(wrongEndpoint, context()), { code: RPC_ERRORS.unavailable }); +}); diff --git a/electron/plugins/byteStreamDatabase.live.test.cjs b/electron/plugins/byteStreamDatabase.live.test.cjs new file mode 100644 index 000000000..8e383bf5f --- /dev/null +++ b/electron/plugins/byteStreamDatabase.live.test.cjs @@ -0,0 +1,78 @@ +"use strict"; + +// Creates only an isolated disposable fixture. Never accepts a user host, +// existing database, database URL, or real credentials from the environment. +const assert = require("node:assert/strict"); +const { test } = require("node:test"); +const { execFileSync } = require("node:child_process"); +const { randomUUID, randomBytes } = require("node:crypto"); +const { pathToFileURL } = require("node:url"); +const path = require("node:path"); +const { PluginByteStreamBroker } = require("./byteStreamBroker.cjs"); +const FIXTURE_IMAGE = "mariadb:11.4@sha256:250e1609e93c0e6aecf64bfbab2d84d5e89d2481540fe77447ff6c855c3b1873"; + +function docker(args, input) { + return execFileSync("docker", args, { input, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 60_000 }).trim(); +} + +test("minimal browser protocol queries a disposable MariaDB through the real byte broker", { + skip: process.env.NETCATTY_BYTE_STREAM_DATABASE_TEST !== "1", + timeout: 120_000, +}, async (t) => { + const suffix = randomUUID().slice(0, 8); + const network = `netcatty-stream-test-${suffix}`; + const container = `netcatty-stream-test-${suffix}`; + const sessionPassword = randomBytes(24).toString("hex"); + docker(["network", "create", "--internal", network]); + let created = false; + t.after(() => { + if (created) docker(["rm", "--force", container]); + docker(["network", "rm", network]); + }); + docker(["run", "--detach", "--rm", "--name", container, "--network", network, + "--env", "MARIADB_ALLOW_EMPTY_ROOT_PASSWORD=1", FIXTURE_IMAGE]); + created = true; + let ready = false; + for (let attempt = 0; attempt < 60; attempt++) { + try { docker(["exec", container, "mariadb-admin", "--host=127.0.0.1", "ping", "--silent"]); ready = true; break; } + catch { await new Promise((resolve) => setTimeout(resolve, 500)); } + } + assert.equal(ready, true, "isolated MariaDB fixture starts"); + docker(["exec", "--interactive", container, "mariadb", "--protocol=socket", "--user=root"], ` +CREATE DATABASE plugin_demo; +CREATE TABLE plugin_demo.example_result (value VARCHAR(64)); +INSERT INTO plugin_demo.example_result VALUES ('synthetic stream result'); +CREATE USER 'plugin_demo'@'%' IDENTIFIED BY '${sessionPassword}'; +GRANT SELECT ON plugin_demo.example_result TO 'plugin_demo'@'%'; +`); + assert.equal(docker(["port", container]), "", "the isolated fixture publishes no host ports"); + const address = docker(["inspect", "--format", "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}", container]); + assert.match(address, /^172\.[0-9]+\.[0-9]+\.[0-9]+$/u); + const endpoint = `tcp://${address}:3306`; + const broker = new PluginByteStreamBroker({ + permissionEngine: { + authorize: async (_context, request) => assert.deepEqual(request.resources, [endpoint]), + onDidRevoke: () => ({ dispose() {} }), + }, + }); + t.after(() => broker.shutdown()); + const context = { pluginId: "com.netcatty.database-minimal", runtimeId: `fixture-${suffix}`, assertActive: async () => {} }; + const { handleId } = await broker.connect(endpoint, context); + const { queryExample, READ_QUERY } = await import(pathToFileURL(path.resolve( + __dirname, "../../examples/plugins/database-minimal/protocol.mjs", + )).href); + assert.equal(READ_QUERY, "SELECT value FROM plugin_demo.example_result LIMIT 1"); + const result = await queryExample({ + read: () => broker.read(handleId, context), + write: (bytes) => broker.write(handleId, bytes, context), + close: () => { if (broker.connections.has(handleId)) broker.close(handleId, context); }, + }, "plugin_demo", sessionPassword); + assert.deepEqual(result, { columns: ["value"], rows: [["synthetic stream result"]] }); + assert.equal(broker.connections.size, 0); + // Server-side grants, not a SQL-prefix check, enforce the read-only fixture. + // MYSQL_PWD exists only inside this disposable test exec and is never logged. + assert.throws(() => execFileSync("docker", ["exec", "--interactive", container, "sh", "-c", + 'read -r MYSQL_PWD; export MYSQL_PWD; exec mariadb --host=127.0.0.1 --user=plugin_demo --execute="INSERT INTO plugin_demo.example_result VALUES (1)"'], + { input: `${sessionPassword}\n`, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }), + (error) => error.status === 1 && /INSERT command denied/u.test(String(error.stderr))); +}); diff --git a/electron/plugins/byteStreamEndpoint.cjs b/electron/plugins/byteStreamEndpoint.cjs new file mode 100644 index 000000000..fe15a5df5 --- /dev/null +++ b/electron/plugins/byteStreamEndpoint.cjs @@ -0,0 +1,53 @@ +"use strict"; + +const net = require("node:net"); + +function failure(_code, message) { return new TypeError(message); } + +function canonicalizeStreamEndpoint(value) { + if (typeof value !== "string" || value.length > 512) { + throw failure("invalidArgument", "Byte stream endpoint is invalid"); + } + // URL's permissive non-special scheme parser accepts paths, userinfo, and + // alternate IPv4 spellings. Require a complete unambiguous authority instead. + const match = /^(tcp|tls):\/\/(\[[0-9a-fA-F:.]+\]|[A-Za-z0-9.-]+):([0-9]{1,5})$/u.exec(value); + if (!match) throw failure("invalidArgument", "Byte streams require an exact TCP or TLS host and port"); + let host = match[2].toLowerCase(); + const port = Number(match[3]); + if (port < 1 || port > 65535 || String(port) !== match[3]) { + throw failure("invalidArgument", "Byte stream port is invalid"); + } + if (host.startsWith("[")) { + host = host.slice(1, -1); + if (net.isIP(host) !== 6) throw failure("invalidArgument", "Byte stream IPv6 address is invalid"); + host = new URL(`http://[${host}]`).hostname.slice(1, -1); + } else if (!net.isIP(host)) { + if (host.length > 253 || /^[0-9.]+$/u.test(host) || host.split(".").some((label) => ( + !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label) + ))) throw failure("invalidArgument", "Byte stream hostname is invalid"); + } + return Object.freeze({ + endpoint: `${match[1]}://${net.isIP(host) === 6 ? `[${host}]` : host}:${port}`, + transport: match[1], host, port, + }); +} + +function isLocalControlAddress(address) { + if (net.isIP(address) === 4) { + const [a, b] = address.split(".").map(Number); + return a === 0 || a === 127 || a >= 224 || (a === 169 && b === 254); + } + if (net.isIP(address) !== 6) return true; + const canonical = new URL(`http://[${address}]`).hostname.slice(1, -1); + if (canonical.startsWith("::ffff:")) { + const words = canonical.slice(7).split(":"); + const n = (parseInt(words[0], 16) * 65536) + parseInt(words[1], 16); + return isLocalControlAddress([n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join(".")); + } + // Also exclude compatible/tunnel addresses that can obscure a local IPv4 peer. + return canonical.startsWith("::") || canonical.startsWith("ff") + || /^fe[89ab]/u.test(canonical) || canonical.startsWith("2002:") + || canonical.startsWith("2001:0:"); +} + +module.exports = { canonicalizeStreamEndpoint, isLocalControlAddress }; diff --git a/electron/plugins/byteStreamEntrypoint.test.cjs b/electron/plugins/byteStreamEntrypoint.test.cjs new file mode 100644 index 000000000..cf8cc1e9a --- /dev/null +++ b/electron/plugins/byteStreamEntrypoint.test.cjs @@ -0,0 +1,126 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); +const fs = require("node:fs/promises"); +const os = require("node:os"); +const path = require("node:path"); +const net = require("node:net"); +const { once } = require("node:events"); +const { createPluginHostService } = require("./hostService.cjs"); +const { inProcessBrowserRuntime } = require("./fixtures/inProcessBrowserRuntime.cjs"); + +test("installed browser entrypoint uses registered SDK/RPC streams, denial and revoke", { timeout: 15_000 }, async (t) => { + const root = await fs.mkdtemp(path.join(os.tmpdir(), "netcatty-byte-entry-")); + let service; + const sockets = new Set(); + const server = net.createServer((socket) => { + sockets.add(socket); + socket.on("close", () => sockets.delete(socket)); + socket.on("error", () => {}); + socket.on("data", (bytes) => socket.write(bytes)); + }); + server.listen(0, "127.0.0.1"); + await once(server, "listening"); + t.after(async () => { + await service?.manager.shutdown(); + for (const socket of sockets) socket.destroy(); + await new Promise((resolve) => server.close(resolve)); + await fs.rm(root, { recursive: true, force: true }); + }); + const endpoint = `tcp://127.0.0.1:${server.address().port}`; + const packageRoot = path.join(root, "source"); + await fs.mkdir(packageRoot); + const id = "com.netcatty.byte-entry-test"; + const manifest = { + manifestVersion: 1, id, name: "byte-entry-test", version: "0.1.0", publisher: "netcatty", + engines: { netcatty: ">=0.0.0", api: ">=0.1.0-internal.1 <0.2.0" }, + main: { browser: "browser.js" }, features: { required: ["network.byte-streams", "ai.model-invocation", "context.selected-read"] }, + activationEvents: [`onCommand:${id}.run`], + permissions: { required: ["commands"], optional: [{ permission: "network.stream", resources: [endpoint] }, "ai.invoke", "context.selected.list", "context.selected.read"] }, + contributes: { commands: ["run", "pending", "cancel", "spoof", "ai", "selected", "aiSpoof"].map((name) => ({ id: `${id}.${name}`, title: name })) }, + }; + await fs.writeFile(path.join(packageRoot, "netcatty.plugin.json"), JSON.stringify(manifest)); + await fs.writeFile(path.join(packageRoot, "browser.js"), ` +export default { activate(context) { + let connection; + for (const name of ["run", "pending", "cancel", "spoof", "ai", "selected", "aiSpoof"]) context.subscriptions.add(context.commands.registerCommand(${JSON.stringify(id)} + "." + name, async () => { + if (name === "aiSpoof") return context.ai.openChat({ sourceOwner: "spoofed" }); + if (name === "selected") { + const selected = await context.selectedContext.list({}); + return context.selectedContext.read({ handle: selected.items[0].handle, version: selected.items[0].version }); + } + if (name === "ai") { + const chat = await context.ai.openChat({}); + try { + const turn = await context.ai.startTurn({ chatHandle: chat.chatHandle, prompt: "synthetic prompt" }); + const events = []; + while (true) { const event = await context.ai.readTurn({ turnHandle: turn.turnHandle }); events.push(event); if (event.kind === "end") return events; } + } finally { await context.ai.closeChat({ chatHandle: chat.chatHandle }); } + } + if (name === "cancel") { await connection?.close(); return true; } + if (name === "spoof") return context.network.connect({ endpoint: ${JSON.stringify(endpoint)}, sourceOwner: "spoofed" }); + connection = await context.network.connect({ endpoint: ${JSON.stringify(endpoint)} }); + if (name === "pending") return { connected: true }; + try { + await connection.writable.write(Uint8Array.of(0, 255, 42)); + return Array.from(await connection.readable.read()); + } finally { await connection.close(); await connection.close(); } + })); +} };`); + let allow = false; + const decisions = []; + service = createPluginHostService({ + app: { getAppPath: () => process.cwd(), getPath: () => root, getVersion: () => "0.0.0" }, + electron: {}, env: {}, + pluginAIHostAdapter: { + assertActive: (context) => context.assertActive(), + selectModel: async () => ({ label: "Synthetic fixture", isCurrent: async () => true, + invoke: async () => (async function* () { yield { kind: "text", text: "synthetic model result" }; yield { kind: "usage", inputTokens: 2, outputTokens: 3, totalTokens: 5 }; })(), + }), + listSelected: async () => [{ key: "fixture", scope: "tab", title: "Synthetic tab", version: "v1", + readText: async () => "synthetic selected text", isCurrent: async () => true }], + reviewText: async () => true, + }, + requestPermissionDecision: async (request) => { + decisions.push(request); + return request.permission === "network.stream" && !allow + ? { requestId: request.requestId, decision: "deny" } + : { requestId: request.requestId, decision: "allow", scope: request.permission === "context.selected.read" ? "once" : "application" }; + }, + }); + // Explicit test-only loopback fixture injection. The production constructor + // exposes no option that forwards these overrides to the broker. + service.byteStreamService.broker.testLocalEndpoints.add(endpoint); + service.byteStreamService.broker.isControlEndpoint = () => false; + service.runtimeSupervisor.runtimeFactories.browser = inProcessBrowserRuntime; + await service.manager.initialize(); + const { buildPluginPackage } = await import("@netcatty/plugin-cli"); + const archive = path.join(root, "fixture.ncpkg"); + await buildPluginPackage(packageRoot, archive); + await service.manager.install(archive, { enable: true }); + const run = (name) => service.contributionService.executeCommand(`${id}.${name}`); + await assert.rejects(run("run"), /denied/u); + assert.equal(service.byteStreamService.broker.connections.size, 0); + allow = true; + assert.deepEqual(await run("run"), [0, 255, 42]); + assert.equal(service.byteStreamService.records.size, 0); + assert.deepEqual(decisions.find((request) => request.permission === "network.stream").resources, [endpoint]); + await assert.rejects(run("spoof"), /contract/u); + assert.deepEqual(await run("ai"), [ + { kind: "text", sequence: 0, text: "synthetic model result" }, + { kind: "usage", sequence: 1, inputTokens: 2, outputTokens: 3, totalTokens: 5 }, + { kind: "end", sequence: 2 }, + ]); + assert.equal((await run("selected")).text, "synthetic selected text"); + await assert.rejects(run("aiSpoof"), /invalid/u); + assert.deepEqual(await run("pending"), { connected: true }); + service.permissionEngine.revokeApplication(id, "network.stream", endpoint); + assert.equal(service.byteStreamService.records.size, 0); + assert.equal(service.byteStreamService.broker.connections.size, 0); + await run("cancel"); + await run("pending"); + await service.manager.setEnabled(id, false); + assert.equal(service.byteStreamService.broker.connections.size, 0); + assert.equal(service.byteStreamService.closedHandles.size, 0); +}); diff --git a/electron/plugins/byteStreamService.cjs b/electron/plugins/byteStreamService.cjs new file mode 100644 index 000000000..effc20213 --- /dev/null +++ b/electron/plugins/byteStreamService.cjs @@ -0,0 +1,206 @@ +"use strict"; + +const { randomUUID } = require("node:crypto"); +const os = require("node:os"); +const { PluginByteStreamBroker, LIMITS } = require("./byteStreamBroker.cjs"); +const { PluginRpcError, RPC_ERRORS } = require("./rpcRouter.cjs"); +const { createDefinitionValidator } = require("./contractValidator.cjs"); + +const FEATURE = require("./generated/plugin-contract.schema.json").$defs.ByteStreamFeature.const; +function denied() { return new PluginRpcError(RPC_ERRORS.permissionDenied, "Byte stream runtime or source binding is invalid"); } +function validator(name) { + const validate = createDefinitionValidator(name); + return (params) => { + if (!validate(params)) throw new PluginRpcError(RPC_ERRORS.invalidArgument, "Byte stream parameters violate the contract"); + return params; + }; +} + +class PluginByteStreamService { + constructor(options) { + this.database = options.database; + this.runtimeSupervisor = options.runtimeSupervisor; + this.records = new Map(); + this.closedHandles = new Map(); + this.closed = false; + this.broker = new PluginByteStreamBroker({ + permissionEngine: options.permissionEngine, + quotaManager: options.quotaManager, + // The public host service never forwards transport fixture overrides. + isControlEndpoint: (address) => Object.values(os.networkInterfaces()).flat().some((item) => item?.address === address), + audit: (pluginId, operation, fields, state) => { + if (this.sourceMatches(state)) this.database.recordSecurityAudit(pluginId, operation, fields); + }, + }); + this.brokerClose = this.broker.onDidClose((state, reason) => { + if (reason) this.closeRecord(this.records.get(state.id), reason); + }); + } + + sourceMatches(identity) { + const active = this.database.getActivePlugin(identity.pluginId); + const retained = this.database.getRetainedPluginSource(identity.pluginId); + return Boolean(active?.enabled && identity.sourceOwner && identity.sourceId + && active.source?.id === identity.sourceId && retained?.id === identity.sourceId + && this.database.privateOwner(identity.pluginId) === identity.sourceOwner + && this.database.publicPluginId(identity.sourceOwner) === identity.pluginId); + } + + async authenticate(context) { + await context.assertActive(); + const assertCommit = () => { + context.signal?.throwIfAborted(); + const current = this.runtimeSupervisor.getRuntimeIdentity(context.pluginId); + if (this.closed || !current || current.runtimeId !== context.runtimeId + || current.pluginVersion !== context.pluginVersion + || current.securityPrincipal !== context.securityPrincipal + || current.sourceOwner !== context.sourceOwner || current.sourceId !== context.sourceId + || !this.sourceMatches(context)) throw denied(); + }; + assertCommit(); + if (!context.manifest?.features?.required?.includes(FEATURE)) { + throw new PluginRpcError(RPC_ERRORS.unsupported, "Byte stream feature was not negotiated"); + } + return Object.freeze({ ...context, assertCommit, + assertActive: async () => { await context.assertActive(); assertCommit(); }, + }); + } + + register(registry) { + // These routes own authorization: connect authenticates before the broker + // obtains its exact endpoint grant; attach/close prove handle ownership. + // The registry public flag skips only the generic permission middleware. + // Runtime authentication and quota middleware still apply to every call. + registry.registerRequest("network.stream.connect", async ({ endpoint }, caller) => { + const context = await this.authenticate(caller); + const handle = await this.broker.connect(endpoint, context); + try { + context.assertCommit(); + this.broker.get(handle.handleId, context); + const record = { + ...handle, context, + inputStreamId: `byte-in-${randomUUID()}`, outputStreamId: `byte-out-${randomUUID()}`, + attached: false, closing: false, input: null, output: null, + }; + this.records.set(handle.handleId, record); + record.abort = () => this.closeRecord(record); + context.signal?.addEventListener("abort", record.abort, { once: true }); + return { ...handle, inputStreamId: record.inputStreamId, + outputStreamId: record.outputStreamId, windowBytes: LIMITS.bufferBytes }; + } catch (error) { + const state = this.broker.connections.get(handle.handleId); + if (state) this.broker.finish(state, error); + throw error; + } + }, { validateParams: validator("ByteStreamConnectRequest"), metadata: { capability: "network.stream", mutating: true, public: true } }); + registry.registerRequest("network.stream.attach", async ({ handleId }, caller) => { + const context = await this.authenticate(caller); + const record = this.get(handleId, context); + if (record.attached) throw new PluginRpcError(RPC_ERRORS.failedPrecondition, "Byte stream is already attached"); + record.attached = true; + try { + record.output = await this.runtimeSupervisor.openStream(context.pluginId, record.outputStreamId, LIMITS.bufferBytes, { + expectedIdentity: context, + onClose: (reason) => { if (reason !== "end") this.closeRecord(record); }, + }); + context.assertCommit(); + if (record.closing) { record.output.cancel(); throw new PluginRpcError(RPC_ERRORS.cancelled, "Byte stream attachment cancelled"); } + context.signal?.addEventListener("abort", record.abort, { once: true }); + // A cancelled attachment cannot leave a producer running after its RPC. + void this.pump(record).finally(() => context.signal?.removeEventListener("abort", record.abort)); + return { attached: true }; + } catch (error) { + try { record.output?.cancel(); } catch {} + this.closeRecord(record, error); + throw error; + } + }, { validateParams: validator("ByteStreamHandleRequest"), metadata: { capability: "network.stream", mutating: true, public: true } }); + registry.registerRequest("network.stream.close", async ({ handleId }, caller) => { + const context = await this.authenticate(caller); + if (!this.wasClosed(handleId, context)) this.closeRecord(this.get(handleId, context)); + return null; + }, { validateParams: validator("ByteStreamHandleRequest"), metadata: { capability: "network.stream", mutating: true, public: true } }); + this.streamRegistration = registry.registerIncomingStream(async (stream, caller) => { + const record = [...this.records.values()].find((item) => item.inputStreamId === stream.streamId); + if (!record) return false; + const context = await this.authenticate(caller); + this.get(record.handleId, context); + if (record.input || stream.windowBytes !== LIMITS.bufferBytes) throw denied(); + record.input = stream; + stream.bind({ + onChunk: async (chunk, release) => { + try { + if (chunk.encoding !== "binary" || !(chunk.bytes instanceof Uint8Array)) throw denied(); + await this.broker.write(record.handleId, chunk.bytes, record.context); + record.context.assertCommit(); + release(); + } catch (error) { this.closeRecord(record, error); } + }, + onClose: () => this.closeRecord(record), + }); + return true; + }); + } + + get(handleId, context) { + const record = this.records.get(handleId); + if (!record || record.closing || record.context.runtimeId !== context.runtimeId + || record.context.pluginId !== context.pluginId || record.context.sourceOwner !== context.sourceOwner + || record.context.sourceId !== context.sourceId) throw denied(); + return record; + } + + wasClosed(handleId, context) { + const owner = this.closedHandles.get(handleId); + return owner && owner.runtimeId === context.runtimeId && owner.pluginId === context.pluginId + && owner.sourceOwner === context.sourceOwner && owner.sourceId === context.sourceId; + } + + async pump(record) { + try { + while (!record.closing) { + const bytes = await this.broker.read(record.handleId, record.context); + if (record.closing) return; + record.context.assertCommit(); + if (bytes === null) { record.output.end(); break; } + await record.output.write(bytes); + } + this.closeRecord(record); + } catch (error) { this.closeRecord(record, error); } + } + + closeRecord(record, reason) { + if (!record || record.closing) return; + record.closing = true; + record.context.signal?.removeEventListener("abort", record.abort); + this.records.delete(record.handleId); + const { pluginId, runtimeId, sourceOwner, sourceId } = record.context; + this.closedHandles.set(record.handleId, { pluginId, runtimeId, sourceOwner, sourceId }); + while (this.closedHandles.size > 256) this.closedHandles.delete(this.closedHandles.keys().next().value); + const state = this.broker.connections.get(record.handleId); + if (state) this.broker.finish(state, reason); + try { record.output?.cancel(); } catch {} + try { void Promise.resolve(record.input?.cancel()).catch(() => {}); } catch {} + } + + releaseRuntime(runtimeId) { + for (const record of this.records.values()) { + if (record.context.runtimeId === runtimeId) this.closeRecord(record); + } + this.broker.releaseRuntime(runtimeId); + for (const [id, owner] of this.closedHandles) { + if (owner.runtimeId === runtimeId) this.closedHandles.delete(id); + } + } + + shutdown() { + this.closed = true; + for (const record of this.records.values()) this.closeRecord(record); + this.broker.shutdown(); + this.brokerClose.dispose(); + this.streamRegistration?.dispose(); + this.closedHandles.clear(); + } +} + +module.exports = { PluginByteStreamService, FEATURE }; diff --git a/electron/plugins/catalogService.cjs b/electron/plugins/catalogService.cjs index dad468923..c3c2da67f 100644 --- a/electron/plugins/catalogService.cjs +++ b/electron/plugins/catalogService.cjs @@ -12,25 +12,29 @@ const { assertPluginJsonValue } = require("./jsonBoundary.cjs"); const MAX_CATALOG_BYTES = 2 * 1024 * 1024; const CATALOG_FIELDS = new Set(["id", "version", "name", "description", "author", "repository", "commit", "license", "readme", "manifest", "artifact"]); -const DOWNLOAD_HOSTS = new Set(["github.com", "raw.githubusercontent.com", "release-assets.githubusercontent.com", "objects.githubusercontent.com"]); -function assertDownloadUrl(value) { +const { OFFICIAL_SOURCE, assertSource } = require("./sourceIdentity.cjs"); +const DISTRIBUTION_ORIGIN = "https://plugins.netcatty.app"; +function assertDownloadUrl(value, origin = DISTRIBUTION_ORIGIN) { + if (typeof value !== "string" || /[\u0000-\u0020\u007f\\%?#]/u.test(value)) { + throw new Error("Catalog download URL is not an approved HTTPS static distribution source"); + } const url = new URL(value); - if (url.protocol !== "https:" || url.username || url.password || url.port || !DOWNLOAD_HOSTS.has(url.hostname)) { - throw new Error("Catalog download URL is not an approved HTTPS GitHub source"); + if (url.origin !== origin || url.username || url.password || url.port + || url.href !== value || url.pathname.split("/").some((part) => part === "." || part === "..")) { + throw new Error("Catalog download URL is not an approved HTTPS static distribution source"); } return url.href; } -function pinnedReadmeUrl(entry) { +function assertReadmeSource(entry) { if (typeof entry.readme !== "string" || /[\u0000-\u001f\u007f\\%?#]/u.test(entry.readme) || entry.readme.split("/").some((segment) => !segment || segment === "." || segment === "..")) { throw new Error("Invalid or unpinned README path"); } - const prefix = `/${entry.repository}/${entry.commit}/`; - const url = new URL(`https://raw.githubusercontent.com${prefix}${entry.readme.split("/").map(encodeURIComponent).join("/")}`); - if (!url.pathname.startsWith(prefix)) throw new Error("README URL escapes the pinned commit"); - return url.href; + if (entry.repository.split("/").some((part) => part === "." || part === "..")) { + throw new Error("README source escapes the pinned commit"); + } } -function validateCatalog(entries) { +function validateCatalog(entries, origin = DISTRIBUTION_ORIGIN) { assertPluginJsonValue(entries, { maxBytes: MAX_CATALOG_BYTES }); if (!Array.isArray(entries) || entries.length > 1000) throw new Error("Invalid plugin catalog"); const ids = new Set(); @@ -43,71 +47,68 @@ function validateCatalog(entries) { || entry.readme.split("/").some((p) => !p || p === "." || p === "..") || /[\\%?#\0]/u.test(entry.readme)) { throw new Error("Invalid or unpinned plugin catalog entry"); } - pinnedReadmeUrl(entry); + assertReadmeSource(entry); if (!validateManifest(entry.manifest)) throw new Error(`Catalog manifest is invalid: ${formatValidationErrors(validateManifest.errors)}`); assertCatalogManifest(entry.manifest, entry); ids.add(entry.id); - if (Object.hasOwn(entry, "artifact")) { - if (!entry.artifact || typeof entry.artifact !== "object" || Array.isArray(entry.artifact) - || Object.keys(entry.artifact).some((key) => key !== "url" && key !== "sha256") - || typeof entry.artifact.url !== "string" || typeof entry.artifact.sha256 !== "string") { - throw new Error("Invalid catalog artifact metadata"); + for (const field of ["artifact"]) { + if (!Object.hasOwn(entry, field)) continue; + const asset = entry[field]; + if (!asset || typeof asset !== "object" || Array.isArray(asset) + || Object.keys(asset).some((key) => key !== "url" && key !== "sha256") + || typeof asset.url !== "string" || typeof asset.sha256 !== "string") { + throw new Error(`Invalid catalog ${field} metadata`); } - assertDownloadUrl(entry.artifact.url); - if (!/^[a-f0-9]{64}$/u.test(entry.artifact.sha256)) throw new Error("Catalog artifact requires SHA-256"); + assertDownloadUrl(asset.url, origin); + if (!/^[a-f0-9]{64}$/u.test(asset.sha256)) throw new Error(`Catalog ${field} requires SHA-256`); } } return entries; } -async function fetchBounded(url, limit, fetchImpl = fetch, maxRedirects = 4) { +async function fetchBounded(url, limit, fetchImpl = fetch, origin = DISTRIBUTION_ORIGIN) { const signal = AbortSignal.timeout(30_000); - for (let redirects = 0; redirects <= maxRedirects; redirects++) { - const response = await fetchImpl(assertDownloadUrl(url), { redirect: "manual", signal, credentials: "omit", referrerPolicy: "no-referrer" }); - if ([301, 302, 303, 307, 308].includes(response.status)) { - await response.body?.cancel(); - url = new URL(response.headers.get("location"), url).href; - continue; - } - if (!response.ok) { await response.body?.cancel(); throw new Error(`Catalog download failed (${response.status})`); } - if (Number(response.headers.get("content-length")) > limit) { - await response.body?.cancel(); throw new Error("Catalog download exceeds size limit"); - } - const reader = response.body?.getReader(); - if (!reader) throw new Error("Catalog download has no body"); - const chunks = []; - let size = 0; - try { - for (;;) { - const { done, value } = await reader.read(); - if (done) break; - size += value.byteLength; - if (size > limit) throw new Error("Catalog download exceeds size limit"); - chunks.push(Buffer.from(value)); - } - return Buffer.concat(chunks, size); - } finally { await reader.cancel(); } + const response = await fetchImpl(assertDownloadUrl(url, origin), { redirect: "manual", signal, credentials: "omit", referrerPolicy: "no-referrer" }); + if ([301, 302, 303, 307, 308].includes(response.status)) { + await response.body?.cancel(); + throw new Error("Catalog redirects are not allowed"); } - throw new Error("Too many catalog redirects"); + if (!response.ok) { await response.body?.cancel(); throw new Error(`Catalog download failed (${response.status})`); } + if (Number(response.headers.get("content-length")) > limit) { + await response.body?.cancel(); throw new Error("Catalog download exceeds size limit"); + } + const reader = response.body?.getReader(); + if (!reader) throw new Error("Catalog download has no body"); + const chunks = []; + let size = 0; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) break; + size += value.byteLength; + if (size > limit) throw new Error("Catalog download exceeds size limit"); + chunks.push(Buffer.from(value)); + } + return Buffer.concat(chunks, size); + } finally { await reader.cancel(); } } class PluginCatalogService { constructor(options) { - this.entries = structuredClone(validateCatalog(options.entries ?? catalog)); + this.marketSource = assertSource(options.source ?? OFFICIAL_SOURCE); + this.origin = this.marketSource.origin; + this.entries = structuredClone(validateCatalog(options.entries ?? (this.marketSource.id === "official" ? catalog : []), this.origin)); this.fetch = options.fetch ?? fetch; this.getTempFilePath = options.getTempFilePath ?? getTempFilePath; this.manager = options.manager; + this.sourceGuard = options.sourceGuard ?? (() => {}); this.installing = false; } list() { return structuredClone(this.entries); } + artifactSize() { return undefined; } get(id) { const entry = this.entries.find((item) => item.id === id); if (!entry) throw new Error("Plugin is not in the curated catalog"); return entry; } - async readme(id) { - const entry = this.get(id); - const url = pinnedReadmeUrl(entry); - return (await fetchBounded(url, 256 * 1024, this.fetch, 0)).toString("utf8"); - } async install(id) { const entry = this.get(id); if (!entry.artifact) throw new Error("This source example has no published package; build and import locally"); @@ -115,16 +116,18 @@ class PluginCatalogService { this.installing = true; let directory; try { - const bytes = await fetchBounded(entry.artifact.url, 32 * 1024 * 1024, this.fetch); + const bytes = await fetchBounded(entry.artifact.url, 32 * 1024 * 1024, this.fetch, this.origin); + const expectedSize = this.artifactSize(entry); + if (expectedSize !== undefined && bytes.byteLength !== expectedSize) throw new Error("Catalog package size mismatch"); if (createHash("sha256").update(bytes).digest("hex") !== entry.artifact.sha256) throw new Error("Catalog package SHA-256 mismatch"); directory = await fs.mkdtemp(this.getTempFilePath("plugin-catalog-")); const archive = path.join(directory, "package.ncpkg"); await fs.writeFile(archive, bytes, { mode: 0o600, flag: "wx" }); - return await this.manager.install(archive, { enable: false, catalog: entry }); + return await this.manager.install(archive, { enable: false, catalog: entry, source: this.marketSource, sourceGuard: this.sourceGuard }); } finally { this.installing = false; if (directory) await fs.rm(directory, { recursive: true, force: true }); } } } -module.exports = { PluginCatalogService, assertDownloadUrl, fetchBounded, validateCatalog, pinnedReadmeUrl, MAX_CATALOG_BYTES }; +module.exports = { PluginCatalogService, assertDownloadUrl, fetchBounded, validateCatalog, assertReadmeSource, MAX_CATALOG_BYTES, DISTRIBUTION_ORIGIN }; diff --git a/electron/plugins/catalogService.test.cjs b/electron/plugins/catalogService.test.cjs index 83d1d4c9c..07531e639 100644 --- a/electron/plugins/catalogService.test.cjs +++ b/electron/plugins/catalogService.test.cjs @@ -24,25 +24,17 @@ test("curated catalog uses pinned public first-party source and rejects advanced assert.throws(() => validateCatalog([{ ...entries[0], commit: "main" }]), /unpinned/); }); -test("README retrieval is bounded and pinned, never follows a redirect to latest", async () => { - const requested = []; - const service = new PluginCatalogService({ entries, fetch: async (url) => { - requested.push(url); return new Response("# First-party example"); - } }); - assert.equal(await service.readme(entries[0].id), "# First-party example"); - assert.equal(requested[0], `https://raw.githubusercontent.com/${entries[0].repository}/${entries[0].commit}/${entries[0].readme}`); - service.fetch = async () => new Response(null, { status: 302, headers: { location: "https://raw.githubusercontent.com/a/b/main/README.md" } }); - await assert.rejects(service.readme(entries[0].id), /redirects/); - await assert.rejects(fetchBounded("https://raw.githubusercontent.com/a/b/c", 3, async () => new Response("1234")), /size limit/); +test("static downloader is bounded and never follows redirects", async () => { + await assert.rejects(fetchBounded("https://plugins.netcatty.app/a", 3, async () => new Response("1234")), /size limit/); await assert.rejects(fetchBounded("https://127.0.0.1/a", 10), /approved HTTPS/); - await assert.rejects(fetchBounded("https://github.com/a", 10, async () => new Response(null, { status: 302, headers: { location: "http://localhost/secret" } })), /approved HTTPS/); + await assert.rejects(fetchBounded("https://plugins.netcatty.app/a", 10, async () => new Response(null, { status: 302, headers: { location: "https://github.com/a" } })), /redirects/); }); test("catalog install verifies the digest, shares manager installation, and never auto-enables", async (context) => { const root = await fs.mkdtemp(path.join(os.tmpdir(), "netcatty-catalog-test-")); context.after(() => fs.rm(root, { recursive: true, force: true })); const bytes = Buffer.from("synthetic bytes: package validation belongs to PackageStore"); - const entry = { ...structuredClone(entries[0]), artifact: { url: "https://github.com/example/repo/releases/download/v1/plugin.ncpkg", sha256: createHash("sha256").update(bytes).digest("hex") } }; + const entry = { ...structuredClone(entries[0]), artifact: { url: "https://plugins.netcatty.app/packages/synthetic.ncpkg", sha256: createHash("sha256").update(bytes).digest("hex") } }; let installs = 0; const service = new PluginCatalogService({ entries: [entry], getTempFilePath: (name) => { assert.equal(name, "plugin-catalog-"); diff --git a/electron/plugins/database.cjs b/electron/plugins/database.cjs index 906491deb..ea1885e65 100644 --- a/electron/plugins/database.cjs +++ b/electron/plugins/database.cjs @@ -5,10 +5,13 @@ const fs = require("node:fs"); const path = require("node:path"); const { DatabaseSync } = require("node:sqlite"); -const SCHEMA_VERSION = 4; +const { LOCAL_SOURCE, assertSource, privateOwner } = require("./sourceIdentity.cjs"); + +const SCHEMA_VERSION = 6; const MAX_SECURITY_AUDIT_DETAILS_BYTES = 16 * 1024; const MAX_SECURITY_AUDIT_RECORDS_PER_PLUGIN = 1_000; const REQUIRED_SCHEMA_COLUMNS = Object.freeze({ + plugin_source_bindings: ["plugin_id", "source_json"], plugin_host_preferences: ["key", "value_json", "updated_at"], plugins: ["id", "enabled", "active_version", "installed_at", "updated_at"], plugin_versions: ["plugin_id", "version", "manifest_json", "archive_sha256", "package_relative_path", "installed_at"], @@ -217,7 +220,27 @@ class PluginDatabase { CREATE TABLE plugin_host_preferences (key TEXT PRIMARY KEY, value_json TEXT NOT NULL, updated_at INTEGER NOT NULL); PRAGMA user_version = 4; `)); + if (version <= 4) this.transaction(() => this.db.exec(` + CREATE TABLE IF NOT EXISTS plugin_source_bindings (plugin_id TEXT PRIMARY KEY, source_json TEXT NOT NULL); + `)); this.#assertSchemaLayout(); + if (version <= 5) this.transaction(() => { + // Upgraded installs and retained local private records must keep their + // provenance after uninstall. Never infer official ownership from names. + const rows = this.db.prepare(` + SELECT id AS plugin_id FROM plugins + UNION SELECT plugin_id FROM plugin_settings + UNION SELECT plugin_id FROM plugin_view_state + UNION SELECT plugin_id FROM plugin_permission_grants + UNION SELECT plugin_id FROM plugin_secrets + UNION SELECT plugin_id FROM plugin_sync_sidecars + `).all(); + const insert = this.db.prepare("INSERT OR IGNORE INTO plugin_source_bindings(plugin_id,source_json) VALUES(?,?)"); + for (const row of rows) { + if (/^[a-z0-9][a-z0-9.-]{1,127}$/u.test(row.plugin_id)) insert.run(row.plugin_id, JSON.stringify(LOCAL_SOURCE)); + } + this.db.exec("PRAGMA user_version = 6"); + }); // Legacy-map backfill is deferred until PackageStore.recover() has finished // (hostService seeds after package initialize). Running here would promote // sole map candidates before recovered manifests are visible, then skip @@ -250,15 +273,64 @@ class PluginDatabase { } } + getPluginSource(pluginId) { + const row = this.db.prepare("SELECT source_json FROM plugin_source_bindings WHERE plugin_id = ?").get(pluginId); + return row ? assertSource(parseJson(row.source_json, "source identity")) : { ...LOCAL_SOURCE }; + } + + getRetainedPluginSource(pluginId) { + const row = this.db.prepare("SELECT source_json FROM plugin_source_bindings WHERE plugin_id = ?").get(pluginId); + if (row) return assertSource(parseJson(row.source_json, "source identity")); + return this.db.prepare("SELECT id FROM plugins WHERE id = ?").get(pluginId) ? { ...LOCAL_SOURCE } : null; + } + + assertInstallSource(pluginId, source = LOCAL_SOURCE) { + const trusted = assertSource(source); + const row = this.db.prepare("SELECT source_json FROM plugin_source_bindings WHERE plugin_id = ?").get(pluginId); + const existing = row ? assertSource(parseJson(row.source_json, "source identity")) + : this.getActivePlugin(pluginId) ? LOCAL_SOURCE : null; + if (existing && existing.id !== trusted.id) { + throw new Error("Plugin source differs. Uninstall and explicitly clear the old source's private data before reinstalling."); + } + return trusted; + } + + privateOwner(pluginId) { + // Opaque owners enter only from host sync storage, never plugin RPC identity. + if (/^source:[a-f0-9]{64}:[a-z0-9][a-z0-9.-]{1,127}$/u.test(pluginId)) return pluginId; + const source = this.getPluginSource(pluginId); + return source.id === "local" ? pluginId : privateOwner(source, pluginId); + } + + publicPluginId(owner) { + if (!owner.startsWith("source:")) return owner; + const pluginId = owner.slice(owner.lastIndexOf(":") + 1); + return this.privateOwner(pluginId) === owner ? pluginId : null; + } + + clearUninstalledSourceData(pluginId, expectedSourceId) { + if (this.getActivePlugin(pluginId)) throw new Error("Uninstall the plugin before changing its source"); + if (this.getPluginSource(pluginId).id !== expectedSourceId) throw new Error("Plugin source changed; review the reset again"); + const owner = this.privateOwner(pluginId); + this.transaction(() => { + for (const table of ["plugin_settings", "plugin_view_state", "plugin_permission_grants", "plugin_secrets", "plugin_sync_sidecars", "plugin_sync_provider_bindings"]) { + this.db.prepare(`DELETE FROM ${table} WHERE plugin_id = ? OR plugin_id = ?`).run(owner, pluginId); + } + this.db.prepare("DELETE FROM plugin_source_bindings WHERE plugin_id = ?").run(pluginId); + }); + } + installVersion(record, options = {}) { if (options.enable === true && options.forceDisabled === true) { throw new TypeError("Plugin version cannot be enabled and force-disabled together"); } + const source = this.assertInstallSource(record.pluginId, record.source); const now = this.clock(); const manifestJson = JSON.stringify(record.manifest); const requestedEnabled = options.enable === true ? 1 : 0; const overwriteEnabled = options.enable === true || options.forceDisabled === true; this.transaction(() => { + this.db.prepare("INSERT INTO plugin_source_bindings(plugin_id,source_json) VALUES(?,?) ON CONFLICT(plugin_id) DO UPDATE SET source_json=excluded.source_json").run(record.pluginId, JSON.stringify(source)); this.db.prepare(` INSERT INTO plugins(id, enabled, active_version, installed_at, updated_at) VALUES (?, ?, ?, ?, ?) @@ -365,6 +437,7 @@ class PluginDatabase { #mapPlugin(row) { return { id: row.id, + source: this.getPluginSource(row.id), enabled: row.enabled === 1, activeVersion: row.active_version ?? null, installedAt: Number(row.installed_at), @@ -498,6 +571,8 @@ class PluginDatabase { } getValue(pluginId, key) { + const owner = this.privateOwner(pluginId); + if (owner !== pluginId) key = `${owner}:${key}`; const row = this.db.prepare( "SELECT value_json FROM plugin_kv WHERE plugin_id = ? AND key = ?", ).get(pluginId, key); @@ -505,6 +580,8 @@ class PluginDatabase { } setValue(pluginId, key, value) { + const owner = this.privateOwner(pluginId); + if (owner !== pluginId) key = `${owner}:${key}`; const serialized = JSON.stringify(value); if (serialized === undefined) throw new TypeError("Plugin storage value must be JSON serializable"); this.db.prepare(` @@ -517,16 +594,22 @@ class PluginDatabase { } deleteValue(pluginId, key) { + const owner = this.privateOwner(pluginId); + if (owner !== pluginId) key = `${owner}:${key}`; this.db.prepare("DELETE FROM plugin_kv WHERE plugin_id = ? AND key = ?").run(pluginId, key); } listKeys(pluginId) { return this.db.prepare( "SELECT key FROM plugin_kv WHERE plugin_id = ? ORDER BY key COLLATE BINARY", - ).all(pluginId).map((row) => row.key); + ).all(pluginId).map((row) => row.key).filter((key) => { + const owner = this.privateOwner(pluginId); + return owner === pluginId || key.startsWith(`${owner}:`); + }).map((key) => this.privateOwner(pluginId) === pluginId ? key : key.slice(this.privateOwner(pluginId).length + 1)); } getSetting(pluginId, settingId, scope, scopeId) { + pluginId = this.privateOwner(pluginId); const row = this.db.prepare(` SELECT value_json FROM plugin_settings WHERE plugin_id = ? AND setting_id = ? AND scope = ? AND scope_id = ? @@ -535,6 +618,7 @@ class PluginDatabase { } setSetting(pluginId, settingId, scope, scopeId, value, updatedAt = this.clock()) { + pluginId = this.privateOwner(pluginId); const serialized = JSON.stringify(value); if (serialized === undefined) throw new TypeError("Plugin setting value must be JSON serializable"); const stamp = Number.isFinite(Number(updatedAt)) ? Number(updatedAt) : this.clock(); @@ -548,6 +632,7 @@ class PluginDatabase { } deleteSetting(pluginId, settingId, scope, scopeId) { + pluginId = this.privateOwner(pluginId); this.db.prepare(` DELETE FROM plugin_settings WHERE plugin_id = ? AND setting_id = ? AND scope = ? AND scope_id = ? @@ -555,6 +640,7 @@ class PluginDatabase { } listSettings(pluginId) { + pluginId = this.privateOwner(pluginId); return this.db.prepare(` SELECT setting_id, scope, scope_id, value_json, updated_at FROM plugin_settings WHERE plugin_id = ? @@ -584,6 +670,7 @@ class PluginDatabase { } getSyncSidecar(pluginId, kind, key) { + pluginId = this.privateOwner(pluginId); const row = this.db.prepare(` SELECT value_json, updated_at FROM plugin_sync_sidecars WHERE plugin_id = ? AND kind = ? AND key = ? @@ -599,6 +686,7 @@ class PluginDatabase { } setSyncSidecar(pluginId, kind, key, value, updatedAt = this.clock()) { + pluginId = this.privateOwner(pluginId); const serialized = JSON.stringify(value); if (serialized === undefined) throw new TypeError("Plugin sync sidecar value must be JSON serializable"); this.db.prepare(` @@ -611,6 +699,7 @@ class PluginDatabase { } deleteSyncSidecar(pluginId, kind, key) { + pluginId = this.privateOwner(pluginId); this.db.prepare(` DELETE FROM plugin_sync_sidecars WHERE plugin_id = ? AND kind = ? AND key = ? @@ -618,6 +707,7 @@ class PluginDatabase { } listSyncSidecars(pluginId) { + pluginId = this.privateOwner(pluginId); return this.db.prepare(` SELECT plugin_id, kind, CAST(key AS BLOB) AS key_bytes, value_json, updated_at FROM plugin_sync_sidecars @@ -672,6 +762,7 @@ class PluginDatabase { } getViewState(pluginId, viewId, scopeId) { + pluginId = this.privateOwner(pluginId); const row = this.db.prepare(` SELECT state_json FROM plugin_view_state WHERE plugin_id = ? AND view_id = ? AND scope_id = ? @@ -680,6 +771,7 @@ class PluginDatabase { } setViewState(pluginId, viewId, scopeId, state) { + pluginId = this.privateOwner(pluginId); const serialized = JSON.stringify(state); if (serialized === undefined) throw new TypeError("Plugin view state must be JSON serializable"); this.db.prepare(` @@ -692,6 +784,7 @@ class PluginDatabase { } deleteViewState(pluginId, viewId, scopeId) { + pluginId = this.privateOwner(pluginId); this.db.prepare(` DELETE FROM plugin_view_state WHERE plugin_id = ? AND view_id = ? AND scope_id = ? @@ -704,8 +797,8 @@ class PluginDatabase { FROM plugin_permission_grants WHERE plugin_id = ? ORDER BY permission COLLATE BINARY, resource COLLATE BINARY - `).all(pluginId).map((row) => ({ - pluginId: row.plugin_id, + `).all(this.privateOwner(pluginId)).map((row) => ({ + pluginId, permission: row.permission, resource: row.resource, resourceKind: row.resource_kind, @@ -724,7 +817,7 @@ class PluginDatabase { declaration_hash = excluded.declaration_hash, granted_at = excluded.granted_at `).run( - record.pluginId, + this.privateOwner(record.pluginId), record.permission, record.resource, record.resourceKind, @@ -734,6 +827,7 @@ class PluginDatabase { } deletePermissionGrant(pluginId, permission, resource) { + pluginId = this.privateOwner(pluginId); this.db.prepare(` DELETE FROM plugin_permission_grants WHERE plugin_id = ? AND permission = ? AND resource = ? @@ -741,10 +835,12 @@ class PluginDatabase { } deleteAllPermissionGrants(pluginId) { + pluginId = this.privateOwner(pluginId); this.db.prepare("DELETE FROM plugin_permission_grants WHERE plugin_id = ?").run(pluginId); } getSecretByKey(pluginId, key) { + pluginId = this.privateOwner(pluginId); const row = this.db.prepare(` SELECT plugin_id, key, secret_ref, ciphertext, created_at, updated_at FROM plugin_secrets WHERE plugin_id = ? AND key = ? @@ -753,6 +849,7 @@ class PluginDatabase { } getSecretByRef(pluginId, secretRef) { + pluginId = this.privateOwner(pluginId); const row = this.db.prepare(` SELECT plugin_id, key, secret_ref, ciphertext, created_at, updated_at FROM plugin_secrets WHERE plugin_id = ? AND secret_ref = ? @@ -762,7 +859,7 @@ class PluginDatabase { #mapSecret(row) { return { - pluginId: row.plugin_id, + pluginId: this.publicPluginId(row.plugin_id), key: row.key, secretRef: row.secret_ref, ciphertext: Buffer.from(row.ciphertext), @@ -782,7 +879,7 @@ class PluginDatabase { ciphertext = excluded.ciphertext, updated_at = excluded.updated_at `).run( - record.pluginId, + this.privateOwner(record.pluginId), record.key, record.secretRef, record.ciphertext, @@ -792,12 +889,14 @@ class PluginDatabase { } deleteSecret(pluginId, key) { + pluginId = this.privateOwner(pluginId); this.db.prepare("DELETE FROM plugin_secrets WHERE plugin_id = ? AND key = ?") .run(pluginId, key); } /** Delete all secrets whose key equals prefix or starts with `${prefix}:`. */ deleteSecretsByKeyPrefix(pluginId, prefix) { + pluginId = this.privateOwner(pluginId); const result = this.db.prepare(` DELETE FROM plugin_secrets WHERE plugin_id = ? @@ -857,7 +956,7 @@ class PluginDatabase { SELECT DISTINCT plugin_id FROM plugin_secrets WHERE key = ? OR key LIKE ? ESCAPE '\\' - `).all(prefix, `${escaped}:%`).map((row) => row.plugin_id); + `).all(prefix, `${escaped}:%`).map((row) => this.publicPluginId(row.plugin_id)).filter((id) => id !== null); } /** diff --git a/electron/plugins/distribution/README.md b/electron/plugins/distribution/README.md new file mode 100644 index 000000000..5040aad7b --- /dev/null +++ b/electron/plugins/distribution/README.md @@ -0,0 +1,16 @@ +# Pinned static distribution schemas + +`delivery.schema.json` and `index.schema.json` are unmodified UTF-8 files from +binaricat/netcatty-plugins commit 7bfe23e5627e16ba63806de6dded5b2667c02984 +(PR 3). The host compiles them with the existing local plugin-contract schema; +no schema reference causes network access. + +`../fixtures/static-distribution/` contains that commit's actual +`distribution/bootstrap/v1/snapshot.json`, snapshot catalog/index/delivery and +four referenced README/PNG assets. Raw-byte SHA-256 checks in +`staticDistribution.test.cjs` verify the publisher's supplied pointer and delivery +hashes; every document and asset is checked against the pointer/sidecar. +The fixture includes no executable plugin package, avatar or credentials. + +Schema revisions must be coordinated with the registry publisher. In particular, +artifact/avatar are deliberately null in v1; do not expand this consumer alone. diff --git a/electron/plugins/distribution/delivery.schema.json b/electron/plugins/distribution/delivery.schema.json new file mode 100644 index 000000000..3bce2a65e --- /dev/null +++ b/electron/plugins/distribution/delivery.schema.json @@ -0,0 +1,166 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Netcatty static delivery v1 (source-only bootstrap)", + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "registryCommit", + "plugins", + "catalogSha256", + "indexSha256", + "sourceLockSha256", + "builderSha256" + ], + "properties": { + "schemaVersion": { + "const": 1 + }, + "registryCommit": { + "type": "string", + "pattern": "^[a-f0-9]{40}$" + }, + "plugins": { + "type": "array", + "maxItems": 1000, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "version", + "repository", + "commit", + "readme", + "iconLight", + "iconDark", + "avatar", + "artifact" + ], + "properties": { + "id": { + "type": "string" + }, + "version": { + "type": "string" + }, + "repository": { + "type": "string" + }, + "commit": { + "type": "string", + "pattern": "^[a-f0-9]{40}$" + }, + "readme": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "sha256", + "size" + ], + "properties": { + "path": { + "type": "string", + "pattern": "^/assets/[a-f0-9]{64}\\.(md|png|webp|ncpkg)$" + }, + "sha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "size": { + "type": "integer", + "minimum": 0, + "maximum": 262144 + } + } + }, + "iconLight": { + "oneOf": [ + { + "type": "null" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "sha256", + "size" + ], + "properties": { + "path": { + "type": "string", + "pattern": "^/assets/[a-f0-9]{64}\\.(md|png|webp|ncpkg)$" + }, + "sha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "size": { + "type": "integer", + "minimum": 0, + "maximum": 262144 + } + } + } + ] + }, + "iconDark": { + "oneOf": [ + { + "type": "null" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "sha256", + "size" + ], + "properties": { + "path": { + "type": "string", + "pattern": "^/assets/[a-f0-9]{64}\\.(md|png|webp|ncpkg)$" + }, + "sha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "size": { + "type": "integer", + "minimum": 0, + "maximum": 262144 + } + } + } + ] + }, + "avatar": { + "type": "null" + }, + "artifact": { + "type": "null" + } + } + } + }, + "catalogSha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "indexSha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "sourceLockSha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "builderSha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + } + } +} diff --git a/electron/plugins/distribution/index.schema.json b/electron/plugins/distribution/index.schema.json new file mode 100644 index 000000000..09746e861 --- /dev/null +++ b/electron/plugins/distribution/index.schema.json @@ -0,0 +1,194 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "plugins" + ], + "properties": { + "schemaVersion": { + "const": 1 + }, + "plugins": { + "type": "array", + "maxItems": 1000, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "current", + "versions" + ], + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^[a-z0-9][a-z0-9.-]+$" + }, + "current": { + "oneOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" + }, + { + "type": "null" + } + ] + }, + "versions": { + "type": "array", + "minItems": 1, + "maxItems": 1000, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "entry", + "distribution", + "withdrawal" + ], + "properties": { + "entry": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "version", + "name", + "description", + "author", + "repository", + "commit", + "license", + "readme", + "manifest" + ], + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^[a-z0-9][a-z0-9.-]+$" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "description": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "author": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "repository": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" + }, + "commit": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^[a-f0-9]{40}$" + }, + "license": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "readme": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "manifest": { + "$ref": "https://netcatty.com/schemas/plugins/0.1.0-internal.1/plugin-contract.schema.json" + }, + "artifact": { + "type": "object", + "additionalProperties": false, + "required": [ + "url", + "sha256" + ], + "properties": { + "url": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "sha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + } + } + } + } + }, + "distribution": { + "enum": [ + "source-only", + "release" + ] + }, + "tag": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" + }, + "withdrawal": { + "oneOf": [ + { + "type": "null" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "at", + "reason", + "advisory" + ], + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "advisory": { + "type": "string", + "pattern": "^https://github.com/" + } + } + } + ] + } + } + } + } + } + } + } + } +} diff --git a/electron/plugins/distributionSnapshot.cjs b/electron/plugins/distributionSnapshot.cjs new file mode 100644 index 000000000..4748d60ac --- /dev/null +++ b/electron/plugins/distributionSnapshot.cjs @@ -0,0 +1,122 @@ +"use strict"; + +const { createHash } = require("node:crypto"); +const { isDeepStrictEqual } = require("node:util"); +const Ajv2020 = require("ajv/dist/2020").default; +const addFormats = require("ajv-formats").default; +const { assertPluginJsonValue } = require("./jsonBoundary.cjs"); +const { fetchBounded, validateCatalog, DISTRIBUTION_ORIGIN, MAX_CATALOG_BYTES } = require("./catalogService.cjs"); +const { formatValidationErrors } = require("./contractValidator.cjs"); +const REGISTRY_URL = `${DISTRIBUTION_ORIGIN}/v1/snapshot.json`; +const SHA256 = /^[a-f0-9]{64}$/u; +const COMMIT = /^[a-f0-9]{40}$/u; +const ajv = new Ajv2020({ allErrors: true, strict: false, validateFormats: true }); +addFormats(ajv); +ajv.addSchema(require("./generated/plugin-contract.schema.json")); +const validateIndex = ajv.compile(require("./distribution/index.schema.json")); +const deliverySchema = require("./distribution/delivery.schema.json"); +const validateDelivery = ajv.compile(deliverySchema); +const deliveryV2 = structuredClone(deliverySchema); +deliveryV2.title = "Netcatty static delivery v2 (hash-bound packages)"; +deliveryV2.properties.schemaVersion.const = 2; +const packageRef = structuredClone(deliveryV2.properties.plugins.items.properties.readme); +packageRef.properties.path.pattern = "^/assets/[a-f0-9]{64}\\.ncpkg$"; +packageRef.properties.size.maximum = 32 * 1024 * 1024; +deliveryV2.properties.plugins.items.properties.artifact = { oneOf: [{ type: "null" }, packageRef] }; +const validateDeliveryV2 = ajv.compile(deliveryV2); +const digest = (bytes) => createHash("sha256").update(bytes).digest("hex"); +const tuple = (entry) => JSON.stringify([entry.id, entry.version, entry.repository, entry.commit]); + +function exactKeys(value, keys) { + return value && typeof value === "object" && !Array.isArray(value) + && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key)); +} +function assertReference(ref, path, limit) { + if (!exactKeys(ref, ["path", "sha256", "size"]) || typeof ref.sha256 !== "string" || !SHA256.test(ref.sha256) + || ref.path !== path || !Number.isSafeInteger(ref.size) || ref.size < 0 || ref.size > limit) { + throw new Error("Invalid static snapshot resource reference"); + } +} +function parseJson(bytes, label, limit = MAX_CATALOG_BYTES) { + const value = JSON.parse(bytes.toString("utf8")); + assertPluginJsonValue(value, { maxBytes: limit }); + if (!value || typeof value !== "object") throw new Error(`Invalid ${label}`); + return value; +} +function assertPointer(pointer) { + if (!exactKeys(pointer, ["schemaVersion", "registryCommit", "snapshotId", "catalog", "index", "delivery"]) + || pointer.schemaVersion !== 1 || typeof pointer.registryCommit !== "string" || !COMMIT.test(pointer.registryCommit) + || typeof pointer.snapshotId !== "string" || !SHA256.test(pointer.snapshotId)) { + throw new Error("Invalid static snapshot pointer"); + } + for (const name of ["catalog", "index", "delivery"]) { + assertReference(pointer[name], `/snapshots/${pointer.snapshotId}/${name}.json`, MAX_CATALOG_BYTES); + } + if (pointer.snapshotId !== pointer.delivery.sha256) throw new Error("Snapshot identity does not match delivery hash"); +} +function assertAsset(ref, extensions) { + if (!ref || typeof ref.path !== "string" || !extensions.some((extension) => ref.path === `/assets/${ref.sha256}.${extension}`)) { + throw new Error("Invalid static asset path or format"); + } + assertReference(ref, ref.path, 256 * 1024); +} +async function fetchVerified(ref, fetchImpl, origin = DISTRIBUTION_ORIGIN) { + const bytes = await fetchBounded(`${origin}${ref.path}`, ref.size, fetchImpl, origin); + if (bytes.byteLength !== ref.size || digest(bytes) !== ref.sha256) throw new Error("Static resource size or SHA-256 mismatch"); + return bytes; +} +function validateSet(pointer, entries, index, delivery, origin = DISTRIBUTION_ORIGIN) { + validateCatalog(entries, origin); + if (!validateIndex(index)) throw new Error(`Invalid distribution index: ${formatValidationErrors(validateIndex.errors)}`); + const validator = delivery.schemaVersion === 2 ? validateDeliveryV2 : validateDelivery; + if (!validator(delivery)) throw new Error(`Invalid static delivery: ${formatValidationErrors(validator.errors)}`); + if (delivery.registryCommit !== pointer.registryCommit || delivery.catalogSha256 !== pointer.catalog.sha256 + || delivery.indexSha256 !== pointer.index.sha256) throw new Error("Static snapshot documents do not match"); + // v1 publishing deliberately refuses packages and avatars. Do not extend this + // consumer ahead of the reviewed publishing schema or invent installable code. + if (delivery.schemaVersion === 1 && entries.some((entry) => entry.artifact)) throw new Error("Static delivery v1 is source-only"); + const current = new Map(); + const indexIds = new Set(); + for (const plugin of index.plugins) { + if (indexIds.has(plugin.id)) throw new Error("Duplicate distribution index plugin"); + indexIds.add(plugin.id); + const versions = new Map(); + for (const version of plugin.versions) { + if (version.entry.id !== plugin.id || versions.has(version.entry.version)) throw new Error("Invalid distribution version identity"); + versions.set(version.entry.version, version); + } + if (plugin.current !== null) { + const version = versions.get(plugin.current); + if (!version || version.withdrawal !== null || (version.distribution !== (version.entry.artifact ? "release" : "source-only"))) throw new Error("Current distribution version is missing or withdrawn"); + current.set(plugin.id, version.entry); + } + } + if (current.size !== entries.length || entries.some((entry) => !isDeepStrictEqual(current.get(entry.id), entry))) { + throw new Error("Catalog does not match the current non-withdrawn index"); + } + const resources = new Map(); + const catalogTuples = new Set(entries.map(tuple)); + for (const plugin of delivery.plugins) { + const key = tuple(plugin); + if (!catalogTuples.has(key) || resources.has(key)) throw new Error("Delivery identity does not match catalog tuple"); + assertAsset(plugin.readme, ["md"]); + for (const icon of [plugin.iconLight, plugin.iconDark]) if (icon !== null) assertAsset(icon, ["png", "webp"]); + const entry = entries.find((item) => tuple(item) === key); + if (plugin.artifact !== null) { + assertReference(plugin.artifact, `/assets/${plugin.artifact.sha256}.ncpkg`, 32 * 1024 * 1024); + if (!entry.artifact || entry.artifact.sha256 !== plugin.artifact.sha256 || entry.artifact.url !== `${origin}${plugin.artifact.path}`) throw new Error("Package delivery does not match catalog hash and source"); + } else if (entry.artifact) throw new Error("Catalog package has no delivery resource"); + resources.set(key, plugin); + } + if (resources.size !== entries.length) throw new Error("Missing delivery entry for catalog plugin"); + return resources; +} +async function fetchDistribution(fetchImpl, origin = DISTRIBUTION_ORIGIN) { + const pointer = parseJson(await fetchBounded(`${origin}/v1/snapshot.json`, 16 * 1024, fetchImpl, origin), "snapshot pointer", 16 * 1024); + assertPointer(pointer); + const documents = await Promise.all(["catalog", "index", "delivery"].map(async (name) => parseJson(await fetchVerified(pointer[name], fetchImpl, origin), name))); + const [entries, index, delivery] = documents; + const resources = validateSet(pointer, entries, index, delivery, origin); + return { entries, resources, pointer }; +} +module.exports = { REGISTRY_URL, fetchDistribution, fetchVerified, tuple, validateSet, assertPointer, assertAsset }; diff --git a/electron/plugins/fixtures/inProcessBrowserRuntime.cjs b/electron/plugins/fixtures/inProcessBrowserRuntime.cjs new file mode 100644 index 000000000..a53f17f20 --- /dev/null +++ b/electron/plugins/fixtures/inProcessBrowserRuntime.cjs @@ -0,0 +1,45 @@ +"use strict"; + +// Test transport harness only. This is Node, not an OS/browser sandbox test. +// Production continues to use the sandboxed BrowserPluginRuntime unchanged. +const { MessageChannel } = require("node:worker_threads"); +const { pathToFileURL } = require("node:url"); +const path = require("node:path"); +const { PluginRpcRouter } = require("../rpcRouter.cjs"); + +function inProcessBrowserRuntime(options) { + let host; + let peer; + let port; + return { + async start(config) { + const { startPluginRuntime } = await import("../runtime/runtimePeer.mjs"); + const { port1, port2 } = new MessageChannel(); + port = port1; + host = new PluginRpcRouter({ pluginId: config.pluginId, + send: (message, transfer) => port1.postMessage(message, transfer), + requestHandlers: options.requestHandlers, notificationHandlers: options.notificationHandlers, + onIncomingStream: options.onIncomingStream, onBeforeMessage: options.onBeforeMessage, + onProtocolError: options.onProtocolError, + }); + port1.on("message", (message) => { void host.accept(message); }); + peer = await startPluginRuntime({ port: port2, config, + loadPlugin: () => import(pathToFileURL(path.join(options.packageRoot, options.plugin.manifest.main.browser)).href), + }); + const initialized = await host.request("plugin.initialize", { + netcattyVersion: config.netcattyVersion, apiVersion: config.apiVersion, supportedFeatures: config.supportedFeatures, + }); + await host.request("plugin.activate", {}); + return initialized; + }, + request: (...args) => host.request(...args), + notify: (...args) => host.notify(...args), + openStream: (...args) => host.streams.openOutgoing(...args), + async stop() { + try { if (host) await host.request("plugin.deactivate", {}); } + finally { await peer?.dispose(); host?.close(); port?.close(); } + }, + }; +} + +module.exports = { inProcessBrowserRuntime }; diff --git a/electron/plugins/fixtures/static-distribution/assets/1692573445e3688b4fe3612282becc086b191a034c0609deeaaebf615627c209.md b/electron/plugins/fixtures/static-distribution/assets/1692573445e3688b4fe3612282becc086b191a034c0609deeaaebf615627c209.md new file mode 100644 index 000000000..39000bf37 --- /dev/null +++ b/electron/plugins/fixtures/static-distribution/assets/1692573445e3688b4fe3612282becc086b191a034c0609deeaaebf615627c209.md @@ -0,0 +1,53 @@ +# Hello Netcatty + +This package is the runnable internal example for the plugin API. Package and install it to exercise native settings, +command-palette contributions, lazy command and Provider activation, +localization, terminal completion/decoration Providers, and the runtime SDK. + +From the repository root: + +```bash +npm run build:plugin-packages +node packages/plugin-cli/dist/cli.js validate examples/plugins/hello-netcatty +node packages/plugin-cli/dist/cli.js compatibility examples/plugins/hello-netcatty --netcatty 0.0.0 +node packages/plugin-cli/dist/cli.js pack examples/plugins/hello-netcatty --out /tmp/hello-netcatty.ncpkg +``` + +After installation, change **Greeting** under **Settings → Plugins**, then run +**Examples: Say Hello** from the command palette. The setting is read through +the host settings broker and the command handler is registered inside the +sandboxed plugin runtime. Type `netc` at a shell prompt to exercise the bounded +completion Provider, and print `Hello from Netcatty` to exercise the declarative +decoration Provider. Neither Provider receives raw xterm objects or sensitive +terminal input/output streams. + +## Import and inspect + +Launch the normal browser-only plugin build using a fresh Electron +user-data directory for demonstrations. In **Settings > Plugins**, choose +**Import .ncpkg**, select the generated archive, and open its details. Review the +manifest permissions, engine ranges and SHA-256, then choose **Enable**. Native +permission prompts still mediate activation and sensitive operations. + +Importing an update is a manual action and leaves it disabled, including when +the previous version was enabled. Review the new package before enabling it. +Changing unsigned package contents changes its security principal; previous +persistent grants are not transferred to different bytes. + +An incompatible application/API upgrade disables installed plugins before +publishing their contributions. The reason remains in the installed list, and +package files and local data remain available. Returning to a compatible host +requires explicit re-enable. Uninstall is different: package code and local KV +are deleted; user-owned settings, secret storage and sync sidecars are retained. + +For a synthetic demonstration, use only this first-party example, change the +Greeting, invoke **Examples: Say Hello**, disable/re-enable, restart the app and +inspect the package again. Do not connect real hosts or a cloud account. The +existing greeting setting is local; declaring `sync: true` on a non-secret +setting opts it into the existing encrypted settings sidecar. Generic SDK KV +storage does not sync. + +For a demonstration without terminal permissions, use `examples/plugins/starter-netcatty`. +Enabling this lazy example does not grant permissions: required permissions are +requested before its first command/provider activation, and optional permissions +when used. Never treat Enabled as a security certification or grant. diff --git a/electron/plugins/fixtures/static-distribution/assets/7a897a67ae6b652339c77a113d1c759919776fead82d2eefd0238d3c05ba87fe.png b/electron/plugins/fixtures/static-distribution/assets/7a897a67ae6b652339c77a113d1c759919776fead82d2eefd0238d3c05ba87fe.png new file mode 100644 index 000000000..5c13bcc87 Binary files /dev/null and b/electron/plugins/fixtures/static-distribution/assets/7a897a67ae6b652339c77a113d1c759919776fead82d2eefd0238d3c05ba87fe.png differ diff --git a/electron/plugins/fixtures/static-distribution/assets/d685ec68558c81705f03195ca35a0a62ea6ec75d8837d5ddb5b5a970890aae6e.md b/electron/plugins/fixtures/static-distribution/assets/d685ec68558c81705f03195ca35a0a62ea6ec75d8837d5ddb5b5a970890aae6e.md new file mode 100644 index 000000000..fc157fd65 --- /dev/null +++ b/electron/plugins/fixtures/static-distribution/assets/d685ec68558c81705f03195ca35a0a62ea6ec75d8837d5ddb5b5a970890aae6e.md @@ -0,0 +1,37 @@ +# Plugin Starter + +A minimal first-party browser plugin for learning import, settings and lifecycle. +It requests `commands`, `settings.read`, `menus` and `views`: no terminal text, host credentials, +network, files, secrets or advanced Node access. It works without OS key storage. +Permission declarations are not grants; follow the app's normal mediation. + +From the repository root: + +```sh +npm run build:plugin-packages +node packages/plugin-cli/dist/cli.js validate examples/plugins/starter-netcatty +node packages/plugin-cli/dist/cli.js pack examples/plugins/starter-netcatty --out /tmp/starter-netcatty.ncpkg +``` + +Start the actual app normally with a fresh test profile; no development flag is +needed. Open **Settings > Plugins > Open plugin manager > Installed**, import the package, inspect its +permissions and enable it. Change **Greeting**, then find **Starter: Greeting Panel** (入门:问候面板) +in the command palette. Review the normal permission prompts, then click +**Show greeting** to see the exact preference in the sandboxed panel. +**Starter: Read Greeting** is also listed and refreshes an already-open panel. +The panel inserts text using `textContent`, never HTML. It does not write to +a terminal or connect to a host. Denied permissions remain denied. + +Disable, restart and re-enable to verify the preference persists. Re-importing +the same package leaves it disabled for review. Uninstall removes code and local +KV; user-owned settings remain. The greeting is local only, not cloud-synced. + +The separate Hello Netcatty example demonstrates terminal providers and requests +terminal permissions. Use this Starter for the default no-sensitive-access demo. + + +Version 0.1.2 adds light/dark PNG brand icons in `assets/`. Displaying these +images does not activate the plugin or request permissions. This example now +requires API `>=0.1.0-internal.1 <0.2.0` and `metadata.brand-icon`. +Older Starter 0.1.1 packages remain compatible with the new host. +See [brand icon author instructions](../../../docs/plugin-platform/plugin-icons.md). diff --git a/electron/plugins/fixtures/static-distribution/assets/ec7bcd5e470ee3d3d9f7f77d120a4de7496a9c0ba984094f84e560d240bea947.png b/electron/plugins/fixtures/static-distribution/assets/ec7bcd5e470ee3d3d9f7f77d120a4de7496a9c0ba984094f84e560d240bea947.png new file mode 100644 index 000000000..bd3a7e0e5 Binary files /dev/null and b/electron/plugins/fixtures/static-distribution/assets/ec7bcd5e470ee3d3d9f7f77d120a4de7496a9c0ba984094f84e560d240bea947.png differ diff --git a/electron/plugins/fixtures/static-distribution/catalog.json b/electron/plugins/fixtures/static-distribution/catalog.json new file mode 100644 index 000000000..a8fef8809 --- /dev/null +++ b/electron/plugins/fixtures/static-distribution/catalog.json @@ -0,0 +1,195 @@ +[ + { + "id": "com.netcatty.starter", + "version": "0.1.2", + "name": "Plugin Starter", + "description": "First-party greeting panel, local settings and commands, without terminal or secret access.", + "author": "Netcatty", + "repository": "binaricat/Netcatty", + "commit": "f4a6b205adca486d4e9cda0270e13a9ff0afd7be", + "license": "GPL-3.0-or-later", + "readme": "examples/plugins/starter-netcatty/README.md", + "manifest": { + "manifestVersion": 1, + "id": "com.netcatty.starter", + "name": "starter-netcatty", + "displayName": { + "en": "Plugin Starter", + "zh-CN": "插件入门" + }, + "description": "First-party settings and command example. No terminal, network, filesystem or secret access.", + "version": "0.1.2", + "publisher": "netcatty", + "license": "GPL-3.0-or-later", + "engines": { + "netcatty": ">=0.0.0", + "api": ">=0.1.0-internal.1 <0.2.0" + }, + "main": { + "browser": "dist/index.js" + }, + "activationEvents": [ + "onCommand:com.netcatty.starter.greet", + "onView:com.netcatty.starter.panel" + ], + "permissions": { + "required": [ + "commands", + "settings.read", + "menus", + "views" + ], + "optional": [] + }, + "contributes": { + "settings": [ + { + "id": "com.netcatty.starter.greeting", + "label": { + "en": "Greeting", + "zh-CN": "问候语" + }, + "description": "A local preference for the example command.", + "control": "text", + "scope": "application", + "default": "Hello, synthetic world!" + } + ], + "commands": [ + { + "id": "com.netcatty.starter.greet", + "title": { + "en": "Starter: Read Greeting", + "zh-CN": "入门:读取问候语" + } + } + ], + "menus": [ + { + "command": "com.netcatty.starter.greet", + "location": "commandPalette", + "group": "examples" + } + ], + "views": [ + { + "id": "com.netcatty.starter.panel", + "title": { + "en": "Starter: Greeting Panel", + "zh-CN": "入门:问候面板" + }, + "location": "modal", + "entry": "panel.html" + } + ] + }, + "features": { + "required": [ + "metadata.brand-icon" + ] + }, + "icon": { + "kind": "package", + "light": "assets/logo-light.png", + "dark": "assets/logo-dark.png" + } + } + }, + { + "id": "com.netcatty.hello", + "version": "0.1.0", + "name": "Hello Netcatty", + "description": "First-party example: greeting settings, commands and terminal providers. Build locally and import.", + "author": "Netcatty", + "repository": "binaricat/Netcatty", + "commit": "4336f8fd53a05a48d6bbc9ad3ce0ca88b121862f", + "license": "GPL-3.0-or-later", + "readme": "examples/plugins/hello-netcatty/README.md", + "manifest": { + "$schema": "../../../packages/plugin-contract/schema/plugin-contract.schema.json", + "manifestVersion": 1, + "id": "com.netcatty.hello", + "name": "hello-netcatty", + "displayName": { + "en": "Hello Netcatty", + "zh-CN": "你好,Netcatty" + }, + "description": "Minimal plugin contract and SDK example.", + "version": "0.1.0", + "publisher": "netcatty", + "license": "GPL-3.0-or-later", + "engines": { + "netcatty": ">=0.0.0", + "api": ">=0.1.0-internal <0.2.0" + }, + "main": { + "browser": "dist/index.js" + }, + "activationEvents": [ + "onCommand:com.netcatty.hello.sayHello", + "onProvider:com.netcatty.hello.completion", + "onProvider:com.netcatty.hello.decoration", + "onProvider:com.netcatty.hello.theme" + ], + "permissions": { + "required": [ + "commands", + "settings.read", + "menus", + "provider.terminal", + "terminal.complete", + "terminal.output", + "terminal.decorate" + ], + "optional": [] + }, + "contributes": { + "settings": [ + { + "id": "com.netcatty.hello.greeting", + "label": "Greeting", + "description": "Text used by the example command.", + "control": "text", + "scope": "application", + "default": "Hello from Netcatty" + } + ], + "commands": [ + { + "id": "com.netcatty.hello.sayHello", + "title": "Say Hello", + "category": "Examples" + } + ], + "menus": [ + { + "command": "com.netcatty.hello.sayHello", + "location": "commandPalette", + "group": "examples", + "order": 10 + } + ], + "providers": [ + { + "id": "com.netcatty.hello.completion", + "label": "Hello completion", + "description": "Suggests the example hello command.", + "kind": "terminal.completion" + }, + { + "id": "com.netcatty.hello.decoration", + "label": "Hello decoration", + "description": "Highlights the example greeting in terminal output.", + "kind": "terminal.decoration" + }, + { + "id": "com.netcatty.hello.theme", + "label": "Hello theme", + "description": "Adds a subtle cursor color to the example terminal theme.", + "kind": "terminal.theme" + } + ] + } + } + } +] diff --git a/electron/plugins/fixtures/static-distribution/delivery.json b/electron/plugins/fixtures/static-distribution/delivery.json new file mode 100644 index 000000000..0650b03ed --- /dev/null +++ b/electron/plugins/fixtures/static-distribution/delivery.json @@ -0,0 +1,48 @@ +{ + "builderSha256": "57199cc6a5d30f5f356adb072d51de9e2283dac6e26c647a4404e4c2261c4a70", + "catalogSha256": "47e967516437996e00eac8fbe97699baa72439ba1bf7ae791731e4964bb13774", + "indexSha256": "af2e953e3c631b36a0e712806d0dcfb0a058fd02f2051025eddded8cc115d461", + "plugins": [ + { + "artifact": null, + "avatar": null, + "commit": "f4a6b205adca486d4e9cda0270e13a9ff0afd7be", + "iconDark": { + "path": "/assets/7a897a67ae6b652339c77a113d1c759919776fead82d2eefd0238d3c05ba87fe.png", + "sha256": "7a897a67ae6b652339c77a113d1c759919776fead82d2eefd0238d3c05ba87fe", + "size": 873 + }, + "iconLight": { + "path": "/assets/ec7bcd5e470ee3d3d9f7f77d120a4de7496a9c0ba984094f84e560d240bea947.png", + "sha256": "ec7bcd5e470ee3d3d9f7f77d120a4de7496a9c0ba984094f84e560d240bea947", + "size": 873 + }, + "id": "com.netcatty.starter", + "readme": { + "path": "/assets/d685ec68558c81705f03195ca35a0a62ea6ec75d8837d5ddb5b5a970890aae6e.md", + "sha256": "d685ec68558c81705f03195ca35a0a62ea6ec75d8837d5ddb5b5a970890aae6e", + "size": 2050 + }, + "repository": "binaricat/Netcatty", + "version": "0.1.2" + }, + { + "artifact": null, + "avatar": null, + "commit": "4336f8fd53a05a48d6bbc9ad3ce0ca88b121862f", + "iconDark": null, + "iconLight": null, + "id": "com.netcatty.hello", + "readme": { + "path": "/assets/1692573445e3688b4fe3612282becc086b191a034c0609deeaaebf615627c209.md", + "sha256": "1692573445e3688b4fe3612282becc086b191a034c0609deeaaebf615627c209", + "size": 2951 + }, + "repository": "binaricat/Netcatty", + "version": "0.1.0" + } + ], + "registryCommit": "32578ae27ff86f0151511478d698a1cdc12fb2e0", + "schemaVersion": 1, + "sourceLockSha256": "753711c1860ff0fcc10a558182f8c868d9d06b40e5c8de5522249d0d27b139d6" +} diff --git a/electron/plugins/fixtures/static-distribution/index.json b/electron/plugins/fixtures/static-distribution/index.json new file mode 100644 index 000000000..6d973e3ff --- /dev/null +++ b/electron/plugins/fixtures/static-distribution/index.json @@ -0,0 +1,218 @@ +{ + "schemaVersion": 1, + "plugins": [ + { + "id": "com.netcatty.starter", + "current": "0.1.2", + "versions": [ + { + "entry": { + "id": "com.netcatty.starter", + "version": "0.1.2", + "name": "Plugin Starter", + "description": "First-party greeting panel, local settings and commands, without terminal or secret access.", + "author": "Netcatty", + "repository": "binaricat/Netcatty", + "commit": "f4a6b205adca486d4e9cda0270e13a9ff0afd7be", + "license": "GPL-3.0-or-later", + "readme": "examples/plugins/starter-netcatty/README.md", + "manifest": { + "manifestVersion": 1, + "id": "com.netcatty.starter", + "name": "starter-netcatty", + "displayName": { + "en": "Plugin Starter", + "zh-CN": "插件入门" + }, + "description": "First-party settings and command example. No terminal, network, filesystem or secret access.", + "version": "0.1.2", + "publisher": "netcatty", + "license": "GPL-3.0-or-later", + "engines": { + "netcatty": ">=0.0.0", + "api": ">=0.1.0-internal.1 <0.2.0" + }, + "main": { + "browser": "dist/index.js" + }, + "activationEvents": [ + "onCommand:com.netcatty.starter.greet", + "onView:com.netcatty.starter.panel" + ], + "permissions": { + "required": [ + "commands", + "settings.read", + "menus", + "views" + ], + "optional": [] + }, + "contributes": { + "settings": [ + { + "id": "com.netcatty.starter.greeting", + "label": { + "en": "Greeting", + "zh-CN": "问候语" + }, + "description": "A local preference for the example command.", + "control": "text", + "scope": "application", + "default": "Hello, synthetic world!" + } + ], + "commands": [ + { + "id": "com.netcatty.starter.greet", + "title": { + "en": "Starter: Read Greeting", + "zh-CN": "入门:读取问候语" + } + } + ], + "menus": [ + { + "command": "com.netcatty.starter.greet", + "location": "commandPalette", + "group": "examples" + } + ], + "views": [ + { + "id": "com.netcatty.starter.panel", + "title": { + "en": "Starter: Greeting Panel", + "zh-CN": "入门:问候面板" + }, + "location": "modal", + "entry": "panel.html" + } + ] + }, + "features": { + "required": [ + "metadata.brand-icon" + ] + }, + "icon": { + "kind": "package", + "light": "assets/logo-light.png", + "dark": "assets/logo-dark.png" + } + } + }, + "distribution": "source-only", + "withdrawal": null + } + ] + }, + { + "id": "com.netcatty.hello", + "current": "0.1.0", + "versions": [ + { + "entry": { + "id": "com.netcatty.hello", + "version": "0.1.0", + "name": "Hello Netcatty", + "description": "First-party example: greeting settings, commands and terminal providers. Build locally and import.", + "author": "Netcatty", + "repository": "binaricat/Netcatty", + "commit": "4336f8fd53a05a48d6bbc9ad3ce0ca88b121862f", + "license": "GPL-3.0-or-later", + "readme": "examples/plugins/hello-netcatty/README.md", + "manifest": { + "$schema": "../../../packages/plugin-contract/schema/plugin-contract.schema.json", + "manifestVersion": 1, + "id": "com.netcatty.hello", + "name": "hello-netcatty", + "displayName": { + "en": "Hello Netcatty", + "zh-CN": "你好,Netcatty" + }, + "description": "Minimal plugin contract and SDK example.", + "version": "0.1.0", + "publisher": "netcatty", + "license": "GPL-3.0-or-later", + "engines": { + "netcatty": ">=0.0.0", + "api": ">=0.1.0-internal <0.2.0" + }, + "main": { + "browser": "dist/index.js" + }, + "activationEvents": [ + "onCommand:com.netcatty.hello.sayHello", + "onProvider:com.netcatty.hello.completion", + "onProvider:com.netcatty.hello.decoration", + "onProvider:com.netcatty.hello.theme" + ], + "permissions": { + "required": [ + "commands", + "settings.read", + "menus", + "provider.terminal", + "terminal.complete", + "terminal.output", + "terminal.decorate" + ], + "optional": [] + }, + "contributes": { + "settings": [ + { + "id": "com.netcatty.hello.greeting", + "label": "Greeting", + "description": "Text used by the example command.", + "control": "text", + "scope": "application", + "default": "Hello from Netcatty" + } + ], + "commands": [ + { + "id": "com.netcatty.hello.sayHello", + "title": "Say Hello", + "category": "Examples" + } + ], + "menus": [ + { + "command": "com.netcatty.hello.sayHello", + "location": "commandPalette", + "group": "examples", + "order": 10 + } + ], + "providers": [ + { + "id": "com.netcatty.hello.completion", + "label": "Hello completion", + "description": "Suggests the example hello command.", + "kind": "terminal.completion" + }, + { + "id": "com.netcatty.hello.decoration", + "label": "Hello decoration", + "description": "Highlights the example greeting in terminal output.", + "kind": "terminal.decoration" + }, + { + "id": "com.netcatty.hello.theme", + "label": "Hello theme", + "description": "Adds a subtle cursor color to the example terminal theme.", + "kind": "terminal.theme" + } + ] + } + } + }, + "distribution": "source-only", + "withdrawal": null + } + ] + } + ] +} diff --git a/electron/plugins/fixtures/static-distribution/snapshot.json b/electron/plugins/fixtures/static-distribution/snapshot.json new file mode 100644 index 000000000..7adb2b627 --- /dev/null +++ b/electron/plugins/fixtures/static-distribution/snapshot.json @@ -0,0 +1,20 @@ +{ + "catalog": { + "path": "/snapshots/53e5189d2cb58a02826931d5d6321ad3e556b924ef80d38636dc9e66a7df8c55/catalog.json", + "sha256": "47e967516437996e00eac8fbe97699baa72439ba1bf7ae791731e4964bb13774", + "size": 5739 + }, + "delivery": { + "path": "/snapshots/53e5189d2cb58a02826931d5d6321ad3e556b924ef80d38636dc9e66a7df8c55/delivery.json", + "sha256": "53e5189d2cb58a02826931d5d6321ad3e556b924ef80d38636dc9e66a7df8c55", + "size": 1869 + }, + "index": { + "path": "/snapshots/53e5189d2cb58a02826931d5d6321ad3e556b924ef80d38636dc9e66a7df8c55/index.json", + "sha256": "af2e953e3c631b36a0e712806d0dcfb0a058fd02f2051025eddded8cc115d461", + "size": 7726 + }, + "registryCommit": "32578ae27ff86f0151511478d698a1cdc12fb2e0", + "schemaVersion": 1, + "snapshotId": "53e5189d2cb58a02826931d5d6321ad3e556b924ef80d38636dc9e66a7df8c55" +} diff --git a/electron/plugins/fixtures/staticDistributionFixture.cjs b/electron/plugins/fixtures/staticDistributionFixture.cjs new file mode 100644 index 000000000..1203046eb --- /dev/null +++ b/electron/plugins/fixtures/staticDistributionFixture.cjs @@ -0,0 +1,40 @@ +"use strict"; +const fs = require("node:fs"); +const path = require("node:path"); +const { createHash } = require("node:crypto"); +const root = path.join(__dirname, "static-distribution"); +const digest = (bytes) => createHash("sha256").update(bytes).digest("hex"); +const read = (name) => fs.readFileSync(path.join(root, name)); +const catalog = JSON.parse(read("catalog.json")); +const delivery = JSON.parse(read("delivery.json")); +function realFiles() { + const pointer = JSON.parse(read("snapshot.json")); + const files = new Map([["/v1/snapshot.json", read("snapshot.json")]]); + for (const name of ["catalog", "index", "delivery"]) files.set(pointer[name].path, read(`${name}.json`)); + for (const name of fs.readdirSync(path.join(root, "assets"))) files.set(`/assets/${name}`, read(`assets/${name}`)); + return files; +} +function makeFiles(entries = catalog, mutate = () => {}) { + const index = { schemaVersion: 1, plugins: entries.map((entry) => ({ id: entry.id, current: entry.version, versions: [{ entry: structuredClone(entry), distribution: "source-only", withdrawal: null }] })) }; + const sidecar = { ...structuredClone(delivery), plugins: entries.map((entry) => ({ ...structuredClone(delivery.plugins.find((item) => item.id === entry.id) ?? delivery.plugins[0]), id: entry.id, version: entry.version, repository: entry.repository, commit: entry.commit })) }; + mutate(index, sidecar); + const catalogBytes = Buffer.from(JSON.stringify(entries)); + const indexBytes = Buffer.from(JSON.stringify(index)); + sidecar.catalogSha256 = digest(catalogBytes); sidecar.indexSha256 = digest(indexBytes); + const deliveryBytes = Buffer.from(JSON.stringify(sidecar)); + const snapshotId = digest(deliveryBytes); + const pointer = { schemaVersion: 1, registryCommit: sidecar.registryCommit, snapshotId }; + const files = realFiles(); + for (const [name, bytes] of [["catalog", catalogBytes], ["index", indexBytes], ["delivery", deliveryBytes]]) { + const ref = { path: `/snapshots/${snapshotId}/${name}.json`, size: bytes.length, sha256: digest(bytes) }; + pointer[name] = ref; files.set(ref.path, bytes); + } + files.set("/v1/snapshot.json", Buffer.from(JSON.stringify(pointer))); + return files; +} +function responseFor(files, url) { + if (new URL(url).origin !== "https://plugins.netcatty.app") throw new Error("Unexpected upstream origin"); + const bytes = files.get(new URL(url).pathname); + return bytes ? new Response(bytes) : new Response("Missing fixture", { status: 404 }); +} +module.exports = { root, read, digest, catalog, delivery, realFiles, makeFiles, responseFor }; diff --git a/electron/plugins/generated/plugin-contract.schema.json b/electron/plugins/generated/plugin-contract.schema.json index ebcc2a6a9..9814bfa85 100644 --- a/electron/plugins/generated/plugin-contract.schema.json +++ b/electron/plugins/generated/plugin-contract.schema.json @@ -540,6 +540,439 @@ }, "additionalProperties": false }, + "PluginAIModelInvocationFeature": { + "const": "ai.model-invocation" + }, + "PluginSelectedContextFeature": { + "const": "context.selected-read" + }, + "PluginAIContextLimits": { + "const": { + "contexts": 4, + "inputBytes": 16384, + "chunkBytes": 4096, + "outputBytes": 32768, + "outputTokens": 2048, + "turnMs": 60000 + } + }, + "PluginAIEmptyParams": { + "type": "object", + "required": [], + "properties": {}, + "additionalProperties": false + }, + "PluginAIChatRef": { + "type": "object", + "required": [ + "chatHandle" + ], + "properties": { + "chatHandle": { + "type": "string", + "format": "uuid" + } + }, + "additionalProperties": false + }, + "PluginAITurnRef": { + "type": "object", + "required": [ + "turnHandle" + ], + "properties": { + "turnHandle": { + "type": "string", + "format": "uuid" + } + }, + "additionalProperties": false + }, + "PluginSelectedContextRef": { + "type": "object", + "required": [ + "handle", + "version" + ], + "properties": { + "handle": { + "type": "string", + "format": "uuid" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[^\\u0000]*$" + } + }, + "additionalProperties": false + }, + "PluginSelectedContextSummary": { + "type": "object", + "required": [ + "handle", + "scope", + "title", + "version", + "expiresAt" + ], + "properties": { + "handle": { + "type": "string", + "format": "uuid" + }, + "scope": { + "enum": [ + "workspace", + "tab", + "session", + "host", + "note" + ] + }, + "title": { + "type": "string", + "minLength": 0, + "maxLength": 160, + "pattern": "^[^\\u0000]*$" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[^\\u0000]*$" + }, + "expiresAt": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + "PluginSelectedContextContent": { + "type": "object", + "required": [ + "handle", + "scope", + "title", + "version", + "expiresAt", + "text" + ], + "properties": { + "handle": { + "type": "string", + "format": "uuid" + }, + "scope": { + "enum": [ + "workspace", + "tab", + "session", + "host", + "note" + ] + }, + "title": { + "type": "string", + "minLength": 0, + "maxLength": 160, + "pattern": "^[^\\u0000]*$" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[^\\u0000]*$" + }, + "expiresAt": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "text": { + "type": "string", + "minLength": 0, + "maxLength": 16384, + "pattern": "^[^\\u0000]*$" + } + }, + "additionalProperties": false + }, + "PluginSelectedContextListResult": { + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "maxItems": 5, + "items": { + "$ref": "#/$defs/PluginSelectedContextSummary" + } + } + }, + "additionalProperties": false + }, + "PluginAIChatResult": { + "type": "object", + "required": [ + "chatHandle", + "model", + "expiresAt" + ], + "properties": { + "chatHandle": { + "type": "string", + "format": "uuid" + }, + "model": { + "type": "string", + "minLength": 0, + "maxLength": 160, + "pattern": "^[^\\u0000]*$" + }, + "expiresAt": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + "PluginAIStartTurnParams": { + "type": "object", + "required": [ + "chatHandle", + "prompt" + ], + "properties": { + "chatHandle": { + "type": "string", + "format": "uuid" + }, + "prompt": { + "type": "string", + "minLength": 1, + "maxLength": 16384, + "pattern": "^[^\\u0000]*$" + }, + "contexts": { + "type": "array", + "maxItems": 4, + "items": { + "$ref": "#/$defs/PluginSelectedContextRef" + } + } + }, + "additionalProperties": false + }, + "PluginAITurnResult": { + "type": "object", + "required": [ + "turnHandle", + "maxOutputTokens", + "reservedTokens" + ], + "properties": { + "turnHandle": { + "type": "string", + "format": "uuid" + }, + "maxOutputTokens": { + "const": 2048 + }, + "reservedTokens": { + "type": "integer", + "minimum": 1, + "maximum": 19456 + } + }, + "additionalProperties": false + }, + "PluginAIBooleanResult": { + "type": "object", + "required": [ + "ok" + ], + "properties": { + "ok": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "PluginAIStreamEvent": { + "oneOf": [ + { + "type": "object", + "required": [ + "kind", + "sequence", + "text" + ], + "properties": { + "kind": { + "const": "text" + }, + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 8192 + }, + "text": { + "type": "string", + "minLength": 0, + "maxLength": 4096, + "pattern": "^[^\\u0000]*$" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "required": [ + "kind", + "sequence" + ], + "properties": { + "kind": { + "const": "usage" + }, + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 8192 + }, + "inputTokens": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "totalTokens": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + { + "type": "object", + "required": [ + "kind", + "sequence" + ], + "properties": { + "kind": { + "const": "end" + }, + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 8192 + } + }, + "additionalProperties": false + } + ] + }, + "ByteStreamFeature": { + "const": "network.byte-streams" + }, + "ByteStreamLimits": { + "const": { + "connectionsPerRuntime": 4, + "connectionsTotal": 64, + "chunkBytes": 65536, + "bufferBytes": 65536, + "connectionBytes": 8388608, + "connectMs": 10000, + "idleMs": 30000, + "lifetimeMs": 120000 + } + }, + "ByteStreamEndpoint": { + "description": "An exact outgoing TCP or TLS endpoint. No userinfo, path, wildcard, query, or implicit port. The host further canonicalizes and checks DNS and control addresses.", + "type": "string", + "minLength": 9, + "maxLength": 512, + "pattern": "^(tcp|tls)://(\\[[0-9A-Fa-f:.]+\\]|[A-Za-z0-9.-]+):[1-9][0-9]{0,4}$" + }, + "ByteStreamConnectRequest": { + "type": "object", + "required": [ + "endpoint" + ], + "properties": { + "endpoint": { + "$ref": "#/$defs/ByteStreamEndpoint" + } + }, + "additionalProperties": false + }, + "ByteStreamHandleRequest": { + "type": "object", + "required": [ + "handleId" + ], + "properties": { + "handleId": { + "type": "string", + "format": "uuid" + } + }, + "additionalProperties": false + }, + "ByteStreamConnectionDescriptor": { + "type": "object", + "required": [ + "handleId", + "endpoint", + "inputStreamId", + "outputStreamId", + "windowBytes" + ], + "properties": { + "handleId": { + "type": "string", + "format": "uuid" + }, + "endpoint": { + "$ref": "#/$defs/ByteStreamEndpoint" + }, + "inputStreamId": { + "$ref": "#/$defs/StreamId" + }, + "outputStreamId": { + "$ref": "#/$defs/StreamId" + }, + "windowBytes": { + "const": 65536 + } + }, + "additionalProperties": false + }, + "ByteStreamAttachResult": { + "type": "object", + "required": [ + "attached" + ], + "properties": { + "attached": { + "const": true + } + }, + "additionalProperties": false + }, "NetworkCredentialLeaseFeature": { "const": "network.credential-lease" }, @@ -701,6 +1134,9 @@ "type": "string", "enum": [ "storage", + "ai.invoke", + "context.selected.list", + "context.selected.read", "runtime.advanced", "settings.read", "settings.write", @@ -723,6 +1159,7 @@ "sftp.read", "sftp.write", "network", + "network.stream", "filesystem.read", "filesystem.write", "secrets", @@ -739,6 +1176,9 @@ "type": "string", "enum": [ "storage", + "ai.invoke", + "context.selected.list", + "context.selected.read", "runtime.advanced", "settings.read", "settings.write", @@ -773,6 +1213,7 @@ "type": "string", "enum": [ "network", + "network.stream", "filesystem.read", "filesystem.write", "companion.execute" @@ -825,12 +1266,32 @@ "maxLength": 1024 } }, + "if": { + "properties": { + "permission": { + "const": "network.stream" + } + } + }, + "then": { + "properties": { + "resources": { + "type": "array", + "items": { + "$ref": "#/$defs/ByteStreamEndpoint" + } + } + } + }, "additionalProperties": false }, "PermissionDeclaration": { "oneOf": [ { - "$ref": "#/$defs/PluginPermission" + "$ref": "#/$defs/PluginPermission", + "not": { + "const": "network.stream" + } }, { "$ref": "#/$defs/PermissionResourceDeclaration" @@ -861,6 +1322,23 @@ "maxLength": 1024 } }, + "if": { + "properties": { + "permission": { + "const": "network.stream" + } + } + }, + "then": { + "properties": { + "resources": { + "type": "array", + "items": { + "$ref": "#/$defs/ByteStreamEndpoint" + } + } + } + }, "additionalProperties": false }, "RequiredPermissionDeclaration": { diff --git a/electron/plugins/hostRpcRegistry.cjs b/electron/plugins/hostRpcRegistry.cjs index 36f119c90..764171503 100644 --- a/electron/plugins/hostRpcRegistry.cjs +++ b/electron/plugins/hostRpcRegistry.cjs @@ -79,6 +79,7 @@ function normalizeRuntimeIdentity(identity) { runtimeKind: identity.runtimeKind, ...(identity.manifest === undefined ? {} : { manifest: identity.manifest }), ...(identity.securityPrincipal === undefined ? {} : { securityPrincipal: identity.securityPrincipal }), + ...(identity.sourceOwner === undefined ? {} : { sourceOwner: identity.sourceOwner, sourceId: identity.sourceId }), ...(identity.packageRoot === undefined ? {} : { packageRoot: identity.packageRoot }), ...(identity.logger === undefined ? {} : { logger: identity.logger }), }); diff --git a/electron/plugins/hostService.cjs b/electron/plugins/hostService.cjs index 8b2208ebc..dc636ce59 100644 --- a/electron/plugins/hostService.cjs +++ b/electron/plugins/hostService.cjs @@ -21,12 +21,15 @@ const { createUtilityModuleMappings, normalizePluginModuleResources, } = require("./moduleResources.cjs"); -const { RegistryCatalogService } = require("./registryCatalogService.cjs"); +const { MarketSourcesService } = require("./marketSourcesService.cjs"); const { PluginThemeService } = require("./themeService.cjs"); const { PackageStore } = require("./packageStore.cjs"); const { createPluginPaths } = require("./paths.cjs"); const { PluginManager } = require("./pluginManager.cjs"); const { PluginNetworkBroker } = require("./networkBroker.cjs"); +const { PluginByteStreamService, FEATURE: BYTE_STREAM_FEATURE } = require("./byteStreamService.cjs"); +const { PluginAIContextService, PLUGIN_AI_CONTEXT_FEATURES } = require("./ai/aiContextService.cjs"); +const { PluginRpcError, RPC_ERRORS } = require("./rpcRouter.cjs"); const { HOST_INTERACTION_FEATURE, PluginHostInteractionService } = require("./hostInteractionService.cjs"); const { PluginPermissionEngine } = require("./permissionEngine.cjs"); const { PluginProtocol } = require("./pluginProtocol.cjs"); @@ -90,8 +93,11 @@ function createPluginHostService(options) { const paths = createPluginPaths(options.app.getPath("userData")); const appRoot = options.appRoot ?? options.app.getAppPath(); const runtimeDirectory = options.runtimeDirectory ?? path.join(__dirname, "runtime"); + const supportedFeatures = [...new Set(["appearance.theme-packs", "metadata.brand-icon", BYTE_STREAM_FEATURE, ...PLUGIN_AI_CONTEXT_FEATURES, NETWORK_CREDENTIAL_LEASE_FEATURE, HOST_INTERACTION_FEATURE, VAULT_PAGES_FEATURE, TERMINAL_SIDEBAR_FEATURE, INTERACTIVE_COMMAND_FEATURE, ...(options.supportedFeatures ?? [])])]; const database = new PluginDatabase(paths.database); let interactionService; + let byteStreamService; + let aiContextService; try { const packageStore = new PackageStore({ allowAdvancedPlugins, @@ -99,7 +105,7 @@ function createPluginHostService(options) { database, netcattyVersion: options.app.getVersion(), apiVersion: PLUGIN_API_VERSION, - supportedFeatures: [...new Set(["appearance.theme-packs", "metadata.brand-icon", NETWORK_CREDENTIAL_LEASE_FEATURE, HOST_INTERACTION_FEATURE, VAULT_PAGES_FEATURE, TERMINAL_SIDEBAR_FEATURE, INTERACTIVE_COMMAND_FEATURE, ...(options.supportedFeatures ?? [])])], + supportedFeatures, }); const contributionIconService = new PluginContributionIconService({ database, @@ -239,7 +245,7 @@ function createPluginHostService(options) { paths, netcattyVersion: options.app.getVersion(), apiVersion: PLUGIN_API_VERSION, - supportedFeatures: [...new Set(["appearance.theme-packs", "metadata.brand-icon", NETWORK_CREDENTIAL_LEASE_FEATURE, HOST_INTERACTION_FEATURE, VAULT_PAGES_FEATURE, TERMINAL_SIDEBAR_FEATURE, INTERACTIVE_COMMAND_FEATURE, ...(options.supportedFeatures ?? [])])], + supportedFeatures, runtimeDirectory, appRoot, rpcRegistry, @@ -249,12 +255,31 @@ function createPluginHostService(options) { getInitialEnvironment: () => contributionService.getEnvironment(), runtimeResourceMonitor: quotaManager, runtimeCleanup: async (identity) => { + byteStreamService?.releaseRuntime(identity.runtimeId); + aiContextService?.releaseRuntime(identity.runtimeId); interactionService?.releaseRuntime(identity.runtimeId); leaseStore.revokeRuntime(identity.runtimeId); await companionSupervisor.releaseRuntime(identity.runtimeId); }, utilityModuleMappings: options.utilityModuleMappings ?? createUtilityModuleMappings(moduleResources), }); + byteStreamService = new PluginByteStreamService({ database, permissionEngine, quotaManager, runtimeSupervisor }); + byteStreamService.register(rpcRegistry); + aiContextService = new PluginAIContextService({ database, permissionEngine, + getRuntimeIdentity: (pluginId) => runtimeSupervisor.getRuntimeIdentity(pluginId), + hostAdapter: options.pluginAIHostAdapter ?? { + assertActive: (context) => context.assertActive(), + selectModel: () => { throw new PluginRpcError(RPC_ERRORS.unavailable, "Plugin model adapter is unavailable"); }, + listSelected: () => [], + reviewText: () => false, + }, + }); + aiContextService.registerRpcCapabilities(rpcRegistry); + const originalOnPluginDisabled = contributionService.onPluginDisabled.bind(contributionService); + contributionService.onPluginDisabled = (pluginId) => { + aiContextService.releasePlugin(pluginId); + return originalOnPluginDisabled(pluginId); + }; runtimeSupervisor.onDidChangeRuntime((event) => contributionService.onRuntimeStateChanged(event)); const terminalProviderService = new PluginTerminalProviderService({ contributionService, @@ -373,6 +398,7 @@ function createPluginHostService(options) { : null; const themeService = new PluginThemeService({database,packageStore,contributionService}); const manager = new PluginManager({ + secretStore, permissionEngine, database, packageStore, @@ -381,6 +407,8 @@ function createPluginHostService(options) { beforeClose: async () => { themeService.shutdown(); interactionService.shutdown(); + byteStreamService.shutdown(); + aiContextService.shutdown(); terminalDataPipelineService?.shutdown(); extensionProviderService.shutdown(); credentialResolver.shutdown?.(); @@ -394,7 +422,7 @@ function createPluginHostService(options) { return { themeService, interactionService, - catalogService: new RegistryCatalogService({ manager, fetch: options.electron.net?.fetch?.bind(options.electron.net) }), + catalogService: new MarketSourcesService({ database, manager, fetch: options.electron.net?.fetch?.bind(options.electron.net) }), companionSupervisor, contributionIconService, contributionService, @@ -411,6 +439,8 @@ function createPluginHostService(options) { paths, protocol, networkBroker, + byteStreamService, + aiContextService, permissionEngine, quotaManager, rpcRegistry, @@ -422,6 +452,8 @@ function createPluginHostService(options) { }; } catch (error) { try { interactionService?.shutdown(); } catch {} + try { byteStreamService?.shutdown(); } catch {} + try { aiContextService?.shutdown(); } catch {} database.close(); throw error; } diff --git a/electron/plugins/marketSourcesService.cjs b/electron/plugins/marketSourcesService.cjs new file mode 100644 index 000000000..202c65ef6 --- /dev/null +++ b/electron/plugins/marketSourcesService.cjs @@ -0,0 +1,42 @@ +"use strict"; +const { PluginSourceRegistry } = require("./sourceRegistry.cjs"); +const { RegistryCatalogService } = require("./registryCatalogService.cjs"); +const { createSourceFetch } = require("./sourceFetch.cjs"); + +class MarketSourcesService { + constructor(options) { + this.options = options; + this.manager = options.manager; + this.registry = new PluginSourceRegistry(options.database); + this.catalogs = new Map(); + } + #catalog(sourceId = "official") { + const source = this.registry.get(sourceId); + let catalog = this.catalogs.get(source.id); + if (!catalog) { + catalog = new RegistryCatalogService({ ...this.options, source, + fetch: source.id === "official" ? this.options.fetch : (this.options.createSourceFetch ?? createSourceFetch)(source.origin), + sourceGuard: () => this.registry.get(source.id), + }); + this.catalogs.set(source.id, catalog); + } + return catalog; + } + list(sourceId) { return this.#catalog(sourceId).list(); } + readme(id, token, sourceId) { return this.#catalog(sourceId).readme(id, token); } + install(id, token, sourceId = "official", acceptedSourceId) { + if (sourceId !== "official" && acceptedSourceId !== sourceId) throw new Error("Review and confirm this third-party source before installing"); + return this.#catalog(sourceId).install(id, token); + } + listSources() { return this.registry.list(); } + addSource(payload) { return this.manager.changeMarketSource(() => this.registry.add(payload?.name, payload?.address)); } + updateSource(payload) { return this.manager.changeMarketSource(() => this.registry.update(payload?.id, payload?.name, payload?.enabled)); } + async removeSource(payload) { + if (typeof payload?.disablePlugins !== "boolean") throw new Error("Choose whether to disable installed plugins"); + await this.manager.changeMarketSource(() => { + this.registry.remove(payload.id); + this.catalogs.delete(payload.id); + }, payload.disablePlugins ? payload.id : undefined); + } +} +module.exports = { MarketSourcesService }; diff --git a/electron/plugins/marketSourcesService.test.cjs b/electron/plugins/marketSourcesService.test.cjs new file mode 100644 index 000000000..dcb5ec08a --- /dev/null +++ b/electron/plugins/marketSourcesService.test.cjs @@ -0,0 +1,40 @@ +"use strict"; +const test = require("node:test"); +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const { PluginDatabase } = require("./database.cjs"); +const { PluginManager } = require("./pluginManager.cjs"); +const { MarketSourcesService } = require("./marketSourcesService.cjs"); +const { realFiles } = require("./fixtures/staticDistributionFixture.cjs"); + +test("source removal retains installed plugins, optional disabling is serialized, and no source silently takes over", async (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "market-sources-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const database = new PluginDatabase(path.join(root, "db.sqlite")); + t.after(() => database.close()); + const stopped = []; + const manager = new PluginManager({ database, packageStore: { async initialize() {} }, runtimeSupervisor: { + async startEnabled() {}, async stop(id) { stopped.push(id); }, + } }); + const requests = []; + const service = new MarketSourcesService({ database, manager, createSourceFetch: (origin) => async (url) => { + assert.equal(new URL(url).origin, origin); requests.push(url); + return new Response(realFiles().get(new URL(url).pathname)); + }, fetch: async () => { assert.fail("third-party browsing must not fetch official upstream"); } }); + const source = await service.addSource({ name: "Community", address: "https://community.example.com" }); + const entry = (await service.list(source.id)).entries[0]; + database.installVersion({ pluginId: entry.id, version: entry.version, manifest: entry.manifest, source, archiveSha256: "a".repeat(64), packageRelativePath: "test" }, { enable: true }); + await assert.rejects(async () => service.install(entry.id, entry.selectionToken, source.id), /confirm/); + await service.updateSource({ id: source.id, name: "Renamed", enabled: false }); + const count = requests.length; + assert.throws(() => service.list(source.id), /disabled/); + assert.equal(database.getActivePlugin(entry.id).enabled, true); + await service.removeSource({ id: source.id, disablePlugins: true }); + assert.equal(database.getActivePlugin(entry.id).enabled, false); + assert.equal(database.getActivePlugin(entry.id).source.id, source.id); + assert.deepEqual(stopped, [entry.id]); + assert.throws(() => service.readme(entry.id, entry.selectionToken, source.id), /removed/); + assert.equal(requests.length, count); +}); diff --git a/electron/plugins/packageStore.cjs b/electron/plugins/packageStore.cjs index 8e4f6d867..268e896af 100644 --- a/electron/plugins/packageStore.cjs +++ b/electron/plugins/packageStore.cjs @@ -1,5 +1,7 @@ "use strict"; +const { LOCAL_SOURCE, assertSource } = require("./sourceIdentity.cjs"); + const { createHash, randomUUID } = require("node:crypto"); const fs = require("node:fs"); const { constants } = fs; @@ -127,6 +129,7 @@ function validateInstallMetadata(value) { version, archiveSha256: value.archiveSha256, contentSha256: value.contentSha256, + source: assertSource(value.source ?? LOCAL_SOURCE), }; } @@ -226,6 +229,7 @@ class PackageStore { const pluginId = assertPluginStorageSegment(manifest.id, "ID"); const version = assertPluginStorageSegment(manifest.version, "version"); const targetDirectory = resolveInstalledVersionDirectory(this.paths, pluginId, version); + const source = this.database.assertInstallSource(pluginId, options.source ?? LOCAL_SOURCE); const previousPlugin = this.database.getActivePlugin(pluginId); if (options.catalog) { if (snapshot.sha256 !== options.catalog.artifact.sha256) throw new Error("Catalog package SHA-256 mismatch"); @@ -266,6 +270,7 @@ class PackageStore { if (previousPlugin?.activeVersion !== version || options.enable === false) await prepareActivation("switch-active-version"); const existingPackage = path.join(targetDirectory, PACKAGE_DIRECTORY); this.database.installVersion({ + source, pluginId, version, manifest: existingValidation.manifest, @@ -282,6 +287,7 @@ class PackageStore { if (!(error && error.code === "ENOENT")) throw error; } const metadata = { + source, pluginId, version, archiveSha256: snapshot.sha256, @@ -299,6 +305,7 @@ class PackageStore { ); try { this.database.installVersion({ + source, pluginId, version, manifest, @@ -391,6 +398,7 @@ class PackageStore { if (metadata.pluginId !== pluginEntry.name || metadata.version !== versionEntry.name) { throw new Error("Plugin install metadata does not match its directory"); } + this.database.assertInstallSource(metadata.pluginId, metadata.source); if (committedVersion && committedVersion.archiveSha256 !== metadata.archiveSha256) { throw new Error("Plugin install archive hash does not match its database record"); } @@ -406,6 +414,7 @@ class PackageStore { if (!committedVersion) { const packageDirectory = path.join(versionDirectory, PACKAGE_DIRECTORY); this.database.installVersion({ + source: metadata.source, pluginId: metadata.pluginId, version: metadata.version, manifest: validation.manifest, @@ -579,6 +588,12 @@ class PackageStore { } } + async clearUninstalledPrivateFiles(pluginId) { + assertPluginStorageSegment(pluginId, "ID"); + if (this.database.getActivePlugin(pluginId)) throw new Error("Plugin is still installed"); + await rm(path.join(this.paths.data, pluginId), { recursive: true, force: true }); + } + async uninstall(pluginId) { const plugin = this.database.getActivePlugin(pluginId); if (!plugin) return false; diff --git a/electron/plugins/permissionEngine.cjs b/electron/plugins/permissionEngine.cjs index 9494c2f83..abea8cdd1 100644 --- a/electron/plugins/permissionEngine.cjs +++ b/electron/plugins/permissionEngine.cjs @@ -201,7 +201,7 @@ class PluginPermissionEngine { } #grantKey(pluginId, permission, declarationHash, resource) { - return `${pluginId}\0${permission}\0${declarationHash}\0${resource}`; + return `${this.database.privateOwner?.(pluginId) ?? pluginId}\0${permission}\0${declarationHash}\0${resource}`; } #sessionGrantKey(sessionId, grantKey) { @@ -219,6 +219,7 @@ class PluginPermissionEngine { ) { return Object.freeze({ pluginId: context.pluginId, + sourceOwner: this.database.privateOwner?.(context.pluginId) ?? context.pluginId, permission, declarationHash, resource, @@ -239,6 +240,7 @@ class PluginPermissionEngine { sessionId, ) { return grant.pluginId === context.pluginId + && grant.sourceOwner === (this.database.privateOwner?.(context.pluginId) ?? context.pluginId) && grant.permission === permission && grant.declarationHash === declarationHash && (grant.scope !== "session" || grant.sessionId === sessionId) diff --git a/electron/plugins/permissionResources.cjs b/electron/plugins/permissionResources.cjs index 3b55e430d..5faa49b8a 100644 --- a/electron/plugins/permissionResources.cjs +++ b/electron/plugins/permissionResources.cjs @@ -2,6 +2,7 @@ const { createHash } = require("node:crypto"); const path = require("node:path"); +const { canonicalizeStreamEndpoint } = require("./byteStreamEndpoint.cjs"); const contractSchema = require("./generated/plugin-contract.schema.json"); @@ -62,6 +63,7 @@ function canonicalizeFilesystemResource(value) { function canonicalizePermissionResource(permission, resource) { assertPluginPermission(permission); + if (permission === "network.stream") return canonicalizeStreamEndpoint(resource).endpoint; if (resource === "*") return resource; if (permission === "network") return canonicalizeNetworkOrigin(resource); if (permission === "companion.execute") return canonicalizeCompanionResource(resource); @@ -86,6 +88,7 @@ function permissionResourceCovers( resourceKind = "exact", requestedResourceKind = "exact", ) { + if (permission === "network.stream") return grantResource !== "*" && grantResource === requestedResource; if (grantResource === "*") return true; if (permission === "filesystem.read" || permission === "filesystem.write") { if (requestedResourceKind === "directory" && resourceKind !== "directory") return false; @@ -112,7 +115,7 @@ function normalizePermissionDeclarations(manifest) { : [...new Set((value.resources ?? []).map((resource) => ( canonicalizePermissionResource(permission, resource) )))].sort(); - if (required && RESOURCE_SCOPED_PERMISSIONS.has(permission)) { + if ((required && RESOURCE_SCOPED_PERMISSIONS.has(permission)) || permission === "network.stream") { if (resources.length === 0) { throw new TypeError(`Required permission ${permission} must declare resources`); } diff --git a/electron/plugins/pluginBridge.cjs b/electron/plugins/pluginBridge.cjs index a5123674a..394551cde 100644 --- a/electron/plugins/pluginBridge.cjs +++ b/electron/plugins/pluginBridge.cjs @@ -25,6 +25,12 @@ const CHANNELS = Object.freeze({ list: "netcatty:plugins:list", permissions: "netcatty:plugins:permissions", revokePermissions: "netcatty:plugins:revoke-permissions", + resetSource: "netcatty:plugins:reset-source", + sourceBinding: "netcatty:plugins:source-binding", + sources: "netcatty:plugins:sources", + addSource: "netcatty:plugins:add-source", + updateSource: "netcatty:plugins:update-source", + removeSource: "netcatty:plugins:remove-source", catalog: "netcatty:plugins:catalog", catalogReadme: "netcatty:plugins:catalog-readme", catalogInstall: "netcatty:plugins:catalog-install", @@ -659,14 +665,18 @@ function registerPluginBridge(ipcMain, options) { ? { credentialStorageAvailable: credentialResolver.isAvailable() } : {}), }; }); - handle(CHANNELS.catalog, async () => options.catalogService?.list() ?? { entries: [], source: "builtin", error: "Plugin catalog unavailable" }); + handle(CHANNELS.sources, async () => options.catalogService?.listSources() ?? []); + handle(CHANNELS.addSource, async (_manager, payload) => options.catalogService.addSource(payload)); + handle(CHANNELS.updateSource, async (_manager, payload) => options.catalogService.updateSource(payload)); + handle(CHANNELS.removeSource, async (_manager, payload) => options.catalogService.removeSource(payload)); + handle(CHANNELS.catalog, async (_manager, payload) => options.catalogService?.list(payload?.sourceId) ?? { entries: [], source: "builtin", error: "Plugin catalog unavailable" }); handle(CHANNELS.catalogReadme, async (_manager, payload) => { if (!options.catalogService) throw new Error("Plugin catalog unavailable"); - return options.catalogService.readme(payload?.id, payload?.selectionToken); + return options.catalogService.readme(payload?.id, payload?.selectionToken, payload?.sourceId); }); handle(CHANNELS.catalogInstall, async (_manager, payload) => { if (!options.catalogService) throw new Error("Plugin catalog unavailable"); - return options.catalogService.install(payload?.id, payload?.selectionToken); + return options.catalogService.install(payload?.id, payload?.selectionToken, payload?.sourceId, payload?.acceptedSourceId); }); handle(CHANNELS.interactionReady, async (_manager, payload, event) => { if (!options.interactionService) throw new Error("Host interactions are unavailable"); @@ -677,6 +687,8 @@ function registerPluginBridge(ipcMain, options) { return options.interactionService.respond(event.sender, payload); }); handle(CHANNELS.list, async (activeManager) => activeManager.list()); + handle(CHANNELS.sourceBinding, async (activeManager, payload) => activeManager.database.getRetainedPluginSource(assertManagedPluginId(payload))); + handle(CHANNELS.resetSource, async (activeManager, payload) => activeManager.resetUninstalledSource(assertManagedPluginId(payload), payload?.expectedSourceId)); const assertManagedPluginId = (payload) => { const id = payload?.pluginId; if (!validateManagedPluginId(id)) { diff --git a/electron/plugins/pluginManager.cjs b/electron/plugins/pluginManager.cjs index 4603e8fea..201868bac 100644 --- a/electron/plugins/pluginManager.cjs +++ b/electron/plugins/pluginManager.cjs @@ -12,6 +12,7 @@ class PluginManager { }; this.beforeClose = options.beforeClose ?? null; this.permissionEngine = options.permissionEngine ?? null; + this.secretStore = options.secretStore ?? null; this.initialized = false; this.initializePromise = null; this.mutationTail = Promise.resolve(); @@ -46,16 +47,37 @@ class PluginManager { return this.database.listPlugins(); } + changeMarketSource(operation, disableSourceId) { + return this.#mutate(async () => { + await this.#ready(); + const result = operation(); + if (disableSourceId) { + const errors = []; + for (const plugin of this.database.listPlugins()) { + if (plugin.source?.id !== disableSourceId) continue; + try { this.database.setEnabled(plugin.id, false); } catch (error) { errors.push(error); } + try { this.contributionService.onPluginDisabled(plugin.id); } catch (error) { errors.push(error); } + try { await this.runtimeSupervisor.stop(plugin.id); } catch (error) { errors.push(error); } + } + if (errors.length) throw new AggregateError(errors, "Source removed, but some plugin shutdown steps failed"); + } + return result; + }); + } + install(archivePath, options) { return this.#mutate(async () => { await this.#ready(); + options?.sourceGuard?.(); let stoppedPlugin = null; let plugin; try { plugin = await this.packageStore.install(archivePath, { enable: options?.enable, catalog: options?.catalog, + source: options?.source, beforeActivate: async ({ pluginId, previousPlugin }) => { + options?.sourceGuard?.(); if (!previousPlugin?.enabled) return; this.database.setEnabled(pluginId, false); this.contributionService.onPluginDisabled(pluginId); @@ -157,6 +179,19 @@ class PluginManager { }); } + resetUninstalledSource(pluginId, expectedSourceId) { + return this.#mutate(async () => { + await this.#ready(); + if (this.database.getActivePlugin(pluginId)) throw new Error("Uninstall the plugin before changing source"); + if (this.database.getPluginSource(pluginId).id !== expectedSourceId) throw new Error("Plugin source changed; review the reset again"); + await this.runtimeSupervisor.stop(pluginId); + this.permissionEngine?.revokeAll(pluginId); + this.secretStore?.clearPluginMemory(pluginId); + await this.packageStore.clearUninstalledPrivateFiles(pluginId); + this.database.clearUninstalledSourceData(pluginId, expectedSourceId); + }); + } + uninstall(pluginId) { return this.#mutate(async () => { await this.#ready(); diff --git a/electron/plugins/pluginSyncSidecarService.cjs b/electron/plugins/pluginSyncSidecarService.cjs index 6633ddf02..8d2b5249b 100644 --- a/electron/plugins/pluginSyncSidecarService.cjs +++ b/electron/plugins/pluginSyncSidecarService.cjs @@ -35,7 +35,7 @@ class PluginSyncSidecarService { sync: setting.sync === true, scope: setting.scope, })); - map.set(plugin.id, fields); + map.set(this.database.privateOwner?.(plugin.id) ?? plugin.id, fields); } return map; } @@ -175,7 +175,7 @@ class PluginSyncSidecarService { if (typeof this.contributionService?.resetSetting === "function") { try { await this.contributionService.resetSetting( - entry.pluginId, + this.database.publicPluginId?.(entry.pluginId) ?? entry.pluginId, parsed.settingId, parsed.scopeId, ); @@ -218,7 +218,7 @@ class PluginSyncSidecarService { if (typeof this.contributionService?.updateSetting === "function") { try { await this.contributionService.updateSetting( - entry.pluginId, + this.database.publicPluginId?.(entry.pluginId) ?? entry.pluginId, parsed.settingId, entry.value, targetScopeId, @@ -312,7 +312,7 @@ class PluginSyncSidecarService { */ async hydrateInstalledPluginSettings(pluginId) { if (typeof pluginId !== "string" || pluginId.length < 1) return; - const declared = this.#declaredSettingsByPlugin().get(pluginId); + const declared = this.#declaredSettingsByPlugin().get(this.database.privateOwner?.(pluginId) ?? pluginId); if (!declared) return; const rows = typeof this.database.listSyncSidecars === "function" ? this.database.listSyncSidecars(pluginId) diff --git a/electron/plugins/registryCatalogService.cjs b/electron/plugins/registryCatalogService.cjs index ef086e49b..c09b65e2c 100644 --- a/electron/plugins/registryCatalogService.cjs +++ b/electron/plugins/registryCatalogService.cjs @@ -1,20 +1,21 @@ "use strict"; const { createHash } = require("node:crypto"); -const { PluginCatalogService, fetchBounded, validateCatalog, MAX_CATALOG_BYTES } = require("./catalogService.cjs"); -const REGISTRY_URL = "https://raw.githubusercontent.com/binaricat/netcatty-plugins/main/catalog.json"; +const { PluginCatalogService, validateCatalog, MAX_CATALOG_BYTES } = require("./catalogService.cjs"); +const { REGISTRY_URL, fetchDistribution, fetchVerified, tuple } = require("./distributionSnapshot.cjs"); const tokenFor = (entry) => createHash("sha256").update(JSON.stringify(entry)).digest("hex"); -function prepareSnapshot(value) { - const entries = structuredClone(validateCatalog(value)); - const publicEntries = structuredClone(entries).map((entry) => ({ ...entry, selectionToken: tokenFor(entry) })); - return { entries, publicEntries }; +function prepareSnapshot(value, resources = new Map(), source) { + const entries = structuredClone(validateCatalog(value, source?.origin)); + const publicEntries = structuredClone(entries).map((entry) => ({ ...entry, selectionToken: tokenFor([source?.id ?? "official", entry, resources.get(tuple(entry)) ?? null]) })); + return { entries, publicEntries, resources: structuredClone(resources) }; } class RegistryCatalogService extends PluginCatalogService { constructor(options) { super(options); - this.publicEntries = prepareSnapshot(this.entries).publicEntries; + this.publicEntries = prepareSnapshot(this.entries, new Map(), this.marketSource).publicEntries; + this.resources = new Map(); this.source = "builtin"; this.error = null; this.refreshing = null; @@ -24,11 +25,12 @@ class RegistryCatalogService extends PluginCatalogService { this.refreshing = (async () => { try { // No redirects: only this exact registry endpoint can replace the catalog. - const bytes = await fetchBounded(REGISTRY_URL, MAX_CATALOG_BYTES, this.fetch, 0); - const next = prepareSnapshot(JSON.parse(bytes.toString("utf8"))); + const distribution = await fetchDistribution(this.fetch, this.origin); + const next = prepareSnapshot(distribution.entries, distribution.resources, this.marketSource); // Publish only after full validation, clones and every token succeeded. this.entries = next.entries; this.publicEntries = next.publicEntries; + this.resources = next.resources; this.source = "registry"; this.error = null; return true; @@ -50,15 +52,17 @@ class RegistryCatalogService extends PluginCatalogService { } selected(id, token) { const entry = this.get(id); - if (typeof token !== "string" || token !== tokenFor(entry)) { + if (typeof token !== "string" || token !== this.publicEntries.find((item) => item.id === id)?.selectionToken) { throw new Error("Catalog entry changed. Refresh and review this version before continuing."); } return entry; } + artifactSize(entry) { return this.resources.get(tuple(entry))?.artifact?.size; } async readme(id, token) { - this.selected(id, token); - // Base method captures the pinned entry synchronously before its first await. - return super.readme(id); + const entry = this.selected(id, token); + const resource = this.resources.get(tuple(entry))?.readme; + if (!resource) throw new Error("No published README snapshot is available. Refresh the catalog or open its source link."); + return (await fetchVerified(resource, this.fetch, this.origin)).toString("utf8"); } async install(id, token) { this.selected(id, token); diff --git a/electron/plugins/registryCatalogService.test.cjs b/electron/plugins/registryCatalogService.test.cjs index ec6e008c6..ed28e4d84 100644 --- a/electron/plugins/registryCatalogService.test.cjs +++ b/electron/plugins/registryCatalogService.test.cjs @@ -1,153 +1,93 @@ "use strict"; const assert = require("node:assert/strict"); const test = require("node:test"); -const { RegistryCatalogService, REGISTRY_URL, MAX_CATALOG_BYTES } = require("./registryCatalogService.cjs"); -const builtin = require("./catalog.json"); +const { RegistryCatalogService, REGISTRY_URL } = require("./registryCatalogService.cjs"); +const { catalog, realFiles, makeFiles, responseFor } = require("./fixtures/staticDistributionFixture.cjs"); -test("registry uses a fixed bounded anonymous endpoint and retains only validated snapshots", async () => { - let response = () => new Response(JSON.stringify([builtin[0]])); +test("registry starts at a fixed anonymous pointer and retains only complete validated snapshots", async () => { + let files = realFiles(); const service = new RegistryCatalogService({ fetch: async (url, options) => { - assert.equal(url, REGISTRY_URL); + assert.equal(new URL(url).origin, "https://plugins.netcatty.app"); assert.equal(options.credentials, "omit"); assert.equal(options.redirect, "manual"); assert.equal(options.referrerPolicy, "no-referrer"); assert.ok(options.signal); - return response(); + return responseFor(files, url); } }); - const online = await service.list(); - assert.equal(online.source, "registry"); assert.equal(online.entries.length, 1); - assert.match(online.entries[0].selectionToken, /^[a-f0-9]{64}$/); - for (const invalid of ["{", '{}', JSON.stringify([{ ...builtin[0], author: {} }]), JSON.stringify([{ ...builtin[0], commit: "main" }])]) { - response = () => new Response(invalid); + const good = await service.list(); + assert.equal(good.source, "registry"); assert.equal(good.entries.length, 2); + assert.match(good.entries[0].selectionToken, /^[a-f0-9]{64}$/); + for (const invalid of ["{", "{}", JSON.stringify({ schemaVersion: 2 }), '{"schemaVersion":1e999}', " ".repeat(16 * 1024 + 1)]) { + files = realFiles(); files.set("/v1/snapshot.json", Buffer.from(invalid)); const cached = await service.list(); assert.equal(cached.source, "cached"); assert.ok(cached.error); - assert.deepEqual(cached.entries, online.entries); + assert.deepEqual(cached.entries, good.entries); } - response = () => new Response("[]", { headers: { "content-length": String(MAX_CATALOG_BYTES + 1) } }); - assert.match((await service.list()).error, /size limit/); - response = () => new Response(null, { status: 302, headers: { location: "https://raw.githubusercontent.com/other/repo/main/catalog.json" } }); - assert.match((await service.list()).error, /redirects/); - response = () => new Response("[]"); - const empty = await service.list(); - assert.equal(empty.error, null); assert.deepEqual(empty.entries, []); + files = makeFiles([]); + assert.deepEqual((await service.list()).entries, []); }); -test("offline first launch returns bundled source examples and never mutates installed plugins", async () => { - const service = new RegistryCatalogService({ fetch: async () => { throw new Error("offline"); }, manager: { +test("offline first launch returns bundled source examples with no GitHub README fallback", async () => { + let calls = 0; + const service = new RegistryCatalogService({ fetch: async (url) => { calls++; assert.equal(url, REGISTRY_URL); throw new Error("offline"); }, manager: { install() { assert.fail("offline must not install"); }, } }); const snapshot = await service.list(); assert.equal(snapshot.source, "builtin"); assert.equal(snapshot.entries.length, 2); - assert.match(snapshot.error, /offline/); + await assert.rejects(service.readme(snapshot.entries[0].id, snapshot.entries[0].selectionToken), /No published README/); + assert.equal(calls, 1); await assert.rejects(service.install(snapshot.entries[0].id, snapshot.entries[0].selectionToken), /browse-only/); }); -test("selection binds manifest, README, version and artifact; refresh changes or withdrawal cannot silently install", async () => { - let entries = structuredClone(builtin); - let requests = 0; - const service = new RegistryCatalogService({ fetch: async (url) => { - requests++; - if (url === REGISTRY_URL) return new Response(JSON.stringify(entries)); - return new Response("# Pinned README"); - }, manager: { install() { assert.fail("changed selection must not install"); } } }); +test("selection binds source and delivery metadata; changes and withdrawal cannot silently install", async () => { + let files = realFiles(); const requests = []; + const service = new RegistryCatalogService({ fetch: async (url) => { requests.push(url); return responseFor(files, url); }, manager: { install() { assert.fail("source-only must not install"); } } }); const selected = (await service.list()).entries[0]; - assert.equal(await service.readme(selected.id, selected.selectionToken), "# Pinned README"); + assert.match(await service.readme(selected.id, selected.selectionToken), /Starter/); await assert.rejects(service.readme(selected.id, "bad"), /changed/); - const before = requests; - await assert.rejects(service.install(selected.id), /changed/); - assert.equal(requests, before); - entries[0].description += " updated"; + const before = requests.length; + await assert.rejects(service.install(selected.id), /changed/); assert.equal(requests.length, before); + await assert.rejects(service.install(selected.id, selected.selectionToken), /no published package/); + const changed = structuredClone(catalog); changed[0].description += " changed"; + files = makeFiles(changed); await assert.rejects(service.install(selected.id, selected.selectionToken), /changed/); await assert.rejects(service.readme(selected.id, selected.selectionToken), /changed/); - entries = []; - const next = (await service.list()).entries; - assert.deepEqual(next, []); + files = makeFiles([]); + assert.deepEqual((await service.list()).entries, []); await assert.rejects(service.install(selected.id, selected.selectionToken), /curated catalog/); }); -test("concurrent list refreshes share one request", async () => { - let finish; let calls = 0; - const service = new RegistryCatalogService({ fetch: async () => { calls++; return new Promise((resolve) => { finish = resolve; }); } }); +test("concurrent list refreshes share one pointer request and complete document set", async () => { + let finish; const requests = []; const files = realFiles(); + const service = new RegistryCatalogService({ fetch: async (url) => { requests.push(url); if (url === REGISTRY_URL) return new Promise((resolve) => { finish = resolve; }); return responseFor(files, url); } }); const first = service.list(); const second = service.list(); - finish(new Response(JSON.stringify(builtin))); - assert.deepEqual(await first, await second); assert.equal(calls, 1); + finish(responseFor(files, REGISTRY_URL)); + assert.deepEqual(await first, await second); assert.equal(requests.length, 4); }); -test("fresh unchanged selection installs only its pinned bytes and stays disabled", async (context) => { - const fs = require("node:fs/promises"); const os = require("node:os"); const path = require("node:path"); - const { createHash } = require("node:crypto"); - const root = await fs.mkdtemp(path.join(os.tmpdir(), "registry-test-")); - context.after(() => fs.rm(root, { recursive: true, force: true })); - const bytes = Buffer.from("synthetic validated-by-manager archive"); - const entry = { ...structuredClone(builtin[0]), artifact: { url: "https://github.com/example/plugin/releases/download/v1/plugin.ncpkg", sha256: createHash("sha256").update(bytes).digest("hex") } }; - const requests = []; let installs = 0; - const service = new RegistryCatalogService({ - getTempFilePath: (name) => path.join(root, name), - fetch: async (url) => { requests.push(url); return new Response(url === REGISTRY_URL ? JSON.stringify([entry]) : bytes); }, - manager: { async install(archive, options) { - installs++; assert.deepEqual(await fs.readFile(archive), bytes); assert.equal(options.enable, false); - assert.deepEqual(options.catalog, entry); return { id: entry.id }; - } }, - }); - const selected = (await service.list()).entries[0]; - await service.install(selected.id, selected.selectionToken); - assert.deepEqual(requests, [REGISTRY_URL, REGISTRY_URL, entry.artifact.url]); - assert.equal(installs, 1); assert.deepEqual(await fs.readdir(root), []); -}); - - -test("URL-stripped README controls cannot escape a selected commit or replace the good snapshot", async () => { - let entries = structuredClone(builtin); - const requested = []; - const service = new RegistryCatalogService({ fetch: async (url) => { - requested.push(url); return new Response(JSON.stringify(entries)); - } }); +test("invalid sources and unknown JSON fields cannot poison good offline snapshots", async () => { + let files = realFiles(); let offline = false; + const service = new RegistryCatalogService({ fetch: async (url) => { if (offline) throw new Error("offline"); return responseFor(files, url); } }); const good = await service.list(); - for (const readme of ["\t../main/README.md", ".\n./main/README.md", "\r../main/README.md", "a/\t../../main/README.md", "README\u007f.md"]) { - entries = [{ ...builtin[0], readme }]; - const snapshot = await service.list(); - assert.equal(snapshot.source, "cached"); assert.match(snapshot.error, /unpinned/); - assert.deepEqual(snapshot.entries, good.entries); - } - entries = [{ ...builtin[0], repository: "example/.." }]; - assert.match((await service.list()).error, /escapes the pinned commit/); - assert.ok(requested.every((url) => url === REGISTRY_URL)); -}); - -test("whole-catalog JSON budgets and unknown fields cannot poison a good offline snapshot", async () => { - let response = JSON.stringify(builtin); - const service = new RegistryCatalogService({ fetch: async () => { - if (response === null) throw new Error("offline"); - return new Response(response); - } }); - const good = await service.list(); - let nested = null; - for (let depth = 0; depth < 130; depth++) nested = { child: nested }; - const nonfinite = structuredClone(builtin[0]); - nonfinite.manifest.contributes.settings[0].default = "finite-marker"; - for (const invalid of [ - JSON.stringify([{ ...builtin[0], unknownNestedField: nested }]), - JSON.stringify([{ ...builtin[0], unknownField: true }]), - JSON.stringify([nonfinite]).replace('"finite-marker"', '1e999'), - JSON.stringify([{ ...builtin[0], artifact: { url: "https://github.com/a/b", sha256: "a".repeat(64), unexpected: true } }]), - ]) { - response = invalid; - const rejected = await service.list(); - assert.equal(rejected.source, "cached"); assert.ok(rejected.error); + let nested = null; for (let i = 0; i < 130; i++) nested = { child: nested }; + const bad = [ + { ...catalog[0], readme: "\t../main/README.md" }, { ...catalog[0], repository: "example/.." }, + { ...catalog[0], unknownNestedField: nested }, { ...catalog[0], unknownField: true }, + { ...catalog[0], readmeAsset: { url: "https://plugins.netcatty.app/a", sha256: "a".repeat(64) } }, + ]; + for (const entry of bad) { + files = makeFiles([entry]); offline = false; + const rejected = await service.list(); assert.equal(rejected.source, "cached"); assert.ok(rejected.error); assert.deepEqual(rejected.entries, good.entries); - response = null; - const offline = await service.list(); - assert.deepEqual(offline.entries, good.entries); assert.match(offline.error, /offline/); + offline = true; assert.deepEqual((await service.list()).entries, good.entries); } }); -test("snapshot preparation failure leaves both private entries and public tokens unchanged", async () => { - const service = new RegistryCatalogService({ fetch: async () => new Response(JSON.stringify(builtin)) }); - const good = await service.list(); +test("snapshot preparation failure leaves private resources and public tokens unchanged", async () => { + const service = new RegistryCatalogService({ fetch: async (url) => responseFor(realFiles(), url) }); + const good = await service.list(); const resources = service.resources; const originalClone = global.structuredClone; - try { - global.structuredClone = () => { throw new Error("synthetic clone failure"); }; - assert.equal(await service.refresh(), false); - } finally { global.structuredClone = originalClone; } + try { global.structuredClone = () => { throw new Error("synthetic clone failure"); }; assert.equal(await service.refresh(), false); } + finally { global.structuredClone = originalClone; } + assert.equal(service.resources, resources); service.fetch = async () => { throw new Error("offline"); }; assert.deepEqual((await service.list()).entries, good.entries); - assert.equal(service.selected(good.entries[0].id, good.entries[0].selectionToken).id, good.entries[0].id); }); diff --git a/electron/plugins/runtime/byteStreamClient.mjs b/electron/plugins/runtime/byteStreamClient.mjs new file mode 100644 index 000000000..4fd15b4ae --- /dev/null +++ b/electron/plugins/runtime/byteStreamClient.mjs @@ -0,0 +1,54 @@ +import { PluginError } from "@netcatty/plugin-sdk"; +import { PLUGIN_BYTE_STREAM_FEATURE } from "@netcatty/plugin-contract"; + +export async function connectByteStream({ client, streams, subscriptions, enabledFeatures }, request, cancellationToken) { + if (!enabledFeatures.includes(PLUGIN_BYTE_STREAM_FEATURE)) throw new PluginError("unsupported", "Byte stream feature is unavailable"); + const descriptor = await client.request("network.stream.connect", request, { cancellationToken }); + let readable; + let writable; + let readablePromise; + let closing; + let cancellation; + let connection; + const close = () => { + closing ??= client.request("network.stream.close", { handleId: descriptor.handleId }) + .finally(() => { + cancellation?.dispose(); + streams.rejectReadable(descriptor.outputStreamId); + if (connection) subscriptions.delete(connection); + }); + return closing; + }; + const cancel = () => { void close().catch(() => {}); }; + const checkCancelled = async () => { + if (!cancellationToken?.isCancellationRequested) return; + await close().catch(() => {}); + throw new PluginError("cancelled", "Byte stream connection cancelled"); + }; + try { + await checkCancelled(); + readablePromise = streams.acceptReadable(descriptor.outputStreamId); + void readablePromise.catch(() => {}); + writable = await streams.openWritable(descriptor.inputStreamId, descriptor.windowBytes); + const attaching = client.request("network.stream.attach", { handleId: descriptor.handleId }, { cancellationToken }); + [readable] = await Promise.all([readablePromise, attaching]); + await checkCancelled(); + connection = Object.freeze({ + endpoint: descriptor.endpoint, + readable: Object.freeze({ + id: readable.id, read: () => readable.read(), cancel, dispose: cancel, + }), + writable: Object.freeze({ + id: writable.id, write: (bytes) => writable.write(bytes), end: () => writable.end(), + fail: cancel, cancel, dispose: cancel, + }), + close, dispose: cancel, + }); + cancellation = cancellationToken?.onCancellationRequested(cancel); + subscriptions.add(connection); + return connection; + } catch (error) { + await close().catch(() => {}); + throw error; + } +} diff --git a/electron/plugins/runtime/runtimePeer.mjs b/electron/plugins/runtime/runtimePeer.mjs index 10d98e62b..52cd17c53 100644 --- a/electron/plugins/runtime/runtimePeer.mjs +++ b/electron/plugins/runtime/runtimePeer.mjs @@ -7,6 +7,7 @@ import { } from "@netcatty/plugin-sdk"; import { createMessagePortStreamEnvelope, PLUGIN_HOST_INTERACTION_LIMITS } from "@netcatty/plugin-contract"; import { createPluginStreamEndpoint } from "./pluginStreamEndpoint.mjs"; +import { connectByteStream } from "./byteStreamClient.mjs"; let terminalInterceptorTransportPromise; @@ -164,6 +165,7 @@ function createHostClient(transport) { const request = pending.get(`${typeof message.id}:${String(message.id)}`); if (!request) return false; pending.delete(`${typeof message.id}:${String(message.id)}`); + request.cancellation?.dispose(); if (message.error) { request.reject(new PluginError( pluginErrorNameFromRpcError(message.error), @@ -174,17 +176,24 @@ function createHostClient(transport) { return true; } function request(method, params, options = {}) { + if (options.cancellationToken?.isCancellationRequested) return Promise.reject(new PluginError("cancelled", "Plugin request cancelled")); const id = nextId; nextId = nextId === Number.MAX_SAFE_INTEGER ? 0 : nextId + 1; return new Promise((resolve, reject) => { - pending.set(`${typeof id}:${String(id)}`, { resolve, reject }); + const cancellationId = options.cancellationToken ? `browser-${id}` : undefined; + const pendingRequest = { resolve, reject }; + pending.set(`${typeof id}:${String(id)}`, pendingRequest); transport.post({ jsonrpc: "2.0", id, method, params, + ...(cancellationId === undefined ? {} : { cancellationId }), ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }), }); + pendingRequest.cancellation = options.cancellationToken?.onCancellationRequested(() => { + notify("$/cancelRequest", { cancellationId }); + }); }); } function notify(method, params) { @@ -192,7 +201,7 @@ function createHostClient(transport) { } function close() { const error = new PluginError("unavailable", "Plugin host disconnected"); - for (const request of pending.values()) request.reject(error); + for (const request of pending.values()) { request.cancellation?.dispose(); request.reject(error); } pending.clear(); } return { accept, request, notify, close }; @@ -376,10 +385,19 @@ function createPluginContext(config, client, runtimeApi) { writeText: (text, title) => interact({ kind: "clipboard.write", title, text }).then((value) => value === true), }; const network = { + connect: (request, cancellationToken) => connectByteStream({ client, streams: runtimeApi.streams, subscriptions, + enabledFeatures: config.enabledFeatures }, request, cancellationToken), request: (request) => client.request("network.request", request, { deadlineMs: forwardedDeadline(request?.timeoutMs, 300_000), }), }; + const ai = Object.fromEntries(["openChat", "startTurn", "readTurn", "stopTurn", "closeChat"].map((operation) => [ + operation, (params) => client.request(`ai.${operation}`, params, operation === "readTurn" ? { deadlineMs: 65_000 } : {}), + ])); + const selectedContext = { + list: (params) => client.request("context.selected.list", params), + read: (params) => client.request("context.selected.read", params), + }; const filesystem = { readFile: (filePath, options = {}) => client.request("filesystem.readFile", { path: filePath, @@ -553,6 +571,8 @@ function createPluginContext(config, client, runtimeApi) { secrets, credentials, network, + ai, + selectedContext, ui, clipboard, filesystem, diff --git a/electron/plugins/runtimeSupervisor.cjs b/electron/plugins/runtimeSupervisor.cjs index 1ed698a68..b9a71adfe 100644 --- a/electron/plugins/runtimeSupervisor.cjs +++ b/electron/plugins/runtimeSupervisor.cjs @@ -239,6 +239,10 @@ class RuntimeSupervisor { signal.throwIfAborted(); const plugin = this.database.getActivePlugin(pluginId); if (!plugin?.manifest || !plugin.packageRelativePath) throw new Error(`Plugin is not installed: ${pluginId}`); + // Capture the host's opaque source owner before async package/placement work. + // Test doubles without provenance APIs cannot use source-bound capabilities. + const sourceOwner = plugin.source && typeof this.database.privateOwner === "function" + ? this.database.privateOwner(pluginId) : null; if (!plugin.enabled) throw new Error(`Plugin is disabled: ${pluginId}`); if (plugin.manifest.main.data) throw new Error("Static theme packs have no executable runtime"); if (plugin.runtime.quarantinedAt != null) throw new Error(`Plugin is quarantined: ${pluginId}`); @@ -273,6 +277,8 @@ class RuntimeSupervisor { const currentPlugin = this.database.getActivePlugin(pluginId); if ( !currentPlugin?.enabled + || (sourceOwner !== null && this.database.privateOwner(pluginId) !== sourceOwner) + || (plugin.source && currentPlugin.source?.id !== plugin.source.id) || currentPlugin.activeVersion !== plugin.activeVersion || currentPlugin.runtime.quarantinedAt != null ) { @@ -286,6 +292,7 @@ class RuntimeSupervisor { runtimeId: randomUUID(), runtimeKind: kind, securityPrincipal, + ...(sourceOwner === null ? {} : { sourceOwner, sourceId: plugin.source.id }), manifest: freezeJson(structuredClone(plugin.manifest)), packageRoot, logger, @@ -294,6 +301,8 @@ class RuntimeSupervisor { if ( this.runtimes.get(pluginId) !== runtime || !active?.enabled + || (sourceOwner !== null && this.database.privateOwner(pluginId) !== sourceOwner) + || (plugin.source && active.source?.id !== plugin.source.id) || active.activeVersion !== plugin.activeVersion || (active.runtime.status !== "starting" && active.runtime.status !== "running") ) { @@ -543,6 +552,7 @@ class RuntimeSupervisor { async #cleanupRuntime(identity) { if (!identity || !this.runtimeCleanup) return; await this.runtimeCleanup(Object.freeze({ + ...(identity.sourceOwner ? { sourceOwner: identity.sourceOwner, sourceId: identity.sourceId } : {}), pluginId: identity.pluginId, pluginVersion: identity.pluginVersion, runtimeId: identity.runtimeId, @@ -575,6 +585,7 @@ class RuntimeSupervisor { runtimeId: identity.runtimeId, runtimeKind: identity.runtimeKind, securityPrincipal: identity.securityPrincipal, + ...(identity.sourceOwner ? { sourceOwner: identity.sourceOwner, sourceId: identity.sourceId } : {}), }); } @@ -651,7 +662,7 @@ class RuntimeSupervisor { if (typeof runtime.openStream !== "function") { throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime cannot receive streams: ${pluginId}`); } - const stream = await runtime.openStream(streamId, windowBytes); + const stream = await runtime.openStream(streamId, windowBytes, { onClose: options?.onClose }); try { const current = await this.#getRunningRuntime(pluginId); if (current.runtime !== runtime || current.identity.runtimeId !== identity.runtimeId) { diff --git a/electron/plugins/secretStore.cjs b/electron/plugins/secretStore.cjs index 356ee0413..eb1b61d4f 100644 --- a/electron/plugins/secretStore.cjs +++ b/electron/plugins/secretStore.cjs @@ -41,7 +41,12 @@ class PluginSecretStore { } #stashKey(pluginId, key) { - return `${pluginId}\0${key}`; + return `${this.database.privateOwner?.(pluginId) ?? pluginId}\0${key}`; + } + + clearPluginMemory(pluginId) { + const prefix = `${this.database.privateOwner?.(pluginId) ?? pluginId}\0`; + for (const key of this.#overwriteStash.keys()) if (key.startsWith(prefix)) this.#overwriteStash.delete(key); } #assertAvailable() { @@ -163,7 +168,7 @@ class PluginSecretStore { } else { deleted = this.database.deleteSecretsByKeyPrefix(pluginId, prefix); } - const pluginPrefix = `${pluginId}\0`; + const pluginPrefix = `${this.database.privateOwner?.(pluginId) ?? pluginId}\0`; for (const stashKey of [...this.#overwriteStash.keys()]) { if (!stashKey.startsWith(pluginPrefix)) continue; const secretKey = stashKey.slice(pluginPrefix.length); diff --git a/electron/plugins/sourceCatalog.test.cjs b/electron/plugins/sourceCatalog.test.cjs new file mode 100644 index 000000000..fa60c568e --- /dev/null +++ b/electron/plugins/sourceCatalog.test.cjs @@ -0,0 +1,59 @@ +"use strict"; +const test = require("node:test"); +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const { RegistryCatalogService } = require("./registryCatalogService.cjs"); +const { thirdPartySource } = require("./sourceIdentity.cjs"); +const { catalog, realFiles, makeFiles, digest } = require("./fixtures/staticDistributionFixture.cjs"); +const first = thirdPartySource("First", "https://first.example.com"); +const second = thirdPartySource("Netcatty", "https://second.example.com"); + +test("identical mirrored catalogs never share selection tokens or offline cache", async () => { + const service = (source) => new RegistryCatalogService({ source, fetch: async (url) => { + assert.equal(new URL(url).origin, source.origin); + return new Response(realFiles().get(new URL(url).pathname)); + } }); + const a = service(first); const b = service(second); + const entryA = (await a.list()).entries[0]; + const entryB = (await b.list()).entries[0]; + assert.notEqual(entryA.selectionToken, entryB.selectionToken); + await assert.rejects(b.readme(entryB.id, entryA.selectionToken), /changed/); + const offline = new RegistryCatalogService({ source: second, fetch: async () => { throw new Error("offline"); } }); + assert.deepEqual((await offline.list()).entries, [], "third-party failure never substitutes the official bundled catalog"); +}); + +test("delivery v2 binds package bytes, size, source and fresh non-withdrawn index before install", async (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "source-catalog-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const bytes = Buffer.from("synthetic package bytes; manager is stubbed"); + const sha256 = digest(bytes); + const asset = `/assets/${sha256}.ncpkg`; + const entry = { ...structuredClone(catalog[0]), artifact: { url: `${first.origin}${asset}`, sha256 } }; + let files = makeFiles([entry], (index, delivery) => { + index.plugins[0].versions[0].distribution = "release"; + delivery.schemaVersion = 2; + delivery.plugins[0].artifact = { path: asset, sha256, size: bytes.length }; + }); + files.set(asset, bytes); + let calls = 0; + const service = new RegistryCatalogService({ source: first, getTempFilePath: (name) => path.join(root, name), fetch: async (url) => { + assert.equal(new URL(url).origin, first.origin); + const body = files.get(new URL(url).pathname); + return body ? new Response(body) : new Response("missing", { status: 404 }); + }, manager: { install(archive, options) { + assert.deepEqual(fs.readFileSync(archive), bytes); + assert.equal(options.enable, false); + assert.equal(options.source.id, first.id); + assert.equal(options.catalog.artifact.sha256, sha256); + calls++; + } } }); + const selected = (await service.list()).entries[0]; + assert.ok(selected, service.error); + await service.install(selected.id, selected.selectionToken); + assert.equal(calls, 1); + files = makeFiles([]); + await assert.rejects(service.install(selected.id, selected.selectionToken), /curated catalog/); + assert.equal(calls, 1); +}); diff --git a/electron/plugins/sourceFetch.cjs b/electron/plugins/sourceFetch.cjs new file mode 100644 index 000000000..4a4b6d4ef --- /dev/null +++ b/electron/plugins/sourceFetch.cjs @@ -0,0 +1,59 @@ +"use strict"; + +const dns = require("node:dns/promises"); +const https = require("node:https"); +const { BlockList, isIPv4 } = require("node:net"); +const { Readable } = require("node:stream"); +const { canonicalSourceOrigin } = require("./sourceIdentity.cjs"); + +const blocked = new BlockList(); +for (const [address, prefix] of [["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4]]) blocked.addSubnet(address, prefix, "ipv4"); +function isPublicAddress(address) { return isIPv4(address) && !blocked.check(address, "ipv4"); } + +// This transport is deliberately separate from plugin network capability access. +// No cookies, credentials, redirects or proxy. DNS is validated and pinned to +// the actual connection, rather than checked separately before another lookup. +function createSourceFetch(origin, options = {}) { + canonicalSourceOrigin(origin); + const resolve4 = options.resolve4 ?? dns.resolve4; + const request = options.request ?? https.get; + return async (value, init = {}) => { + const url = new URL(value); + if (url.origin !== origin || url.username || url.password || url.search || url.hash + || /[\\%\s]/u.test(value) || url.href !== value + || !/^\/(?:v1\/snapshot\.json|snapshots\/[a-f0-9]{64}\/(?:catalog|index|delivery)\.json|assets\/[a-f0-9]{64}\.(?:md|png|webp|ncpkg))$/u.test(url.pathname)) throw new Error("Source resource is outside its static origin or protocol paths"); + init.signal?.throwIfAborted(); + // IPv4-only initial transport: IPv6-only sources fail visibly, never fall + // back to an unchecked resolver. This keeps address classification explicit. + const addresses = await new Promise((resolve, reject) => { + const abort = () => reject(init.signal.reason); + init.signal?.addEventListener("abort", abort, { once: true }); + Promise.resolve().then(() => resolve4(url.hostname)).then(resolve, reject) + .finally(() => init.signal?.removeEventListener("abort", abort)); + }); + init.signal?.throwIfAborted(); + if (!addresses.length || addresses.some((address) => !isPublicAddress(address))) throw new Error("Source DNS resolves to a non-public address"); + const address = addresses[0]; + return new Promise((resolve, reject) => { + const req = request(url, { + agent: false, signal: init.signal, + lookup(_host, opts, callback) { + if (opts?.all) callback(null, [{ address, family: 4 }]); + else callback(null, address, 4); + }, + headers: { accept: "application/json, text/plain, application/octet-stream" }, + }, (response) => { + try { + const status = response.statusCode ?? 502; + // fetchBounded rejects redirects/non-2xx and cancels the stream. + const headers = new Headers(); + for (const [key, value] of Object.entries(response.headers)) if (value !== undefined) headers.set(key, Array.isArray(value) ? value.join(", ") : value); + if ([204, 205, 304].includes(status)) { response.destroy(); resolve(new Response(null, { status, headers })); } + else resolve(new Response(Readable.toWeb(response), { status, headers })); + } catch (error) { response.destroy(); reject(error); } + }); + req.once("error", reject); + }); + }; +} +module.exports = { createSourceFetch, isPublicAddress }; diff --git a/electron/plugins/sourceFetch.test.cjs b/electron/plugins/sourceFetch.test.cjs new file mode 100644 index 000000000..27b4f1c7e --- /dev/null +++ b/electron/plugins/sourceFetch.test.cjs @@ -0,0 +1,47 @@ +"use strict"; +const test = require("node:test"); +const assert = require("node:assert/strict"); +const { createSourceFetch, isPublicAddress } = require("./sourceFetch.cjs"); +const { EventEmitter } = require("node:events"); +const { Readable } = require("node:stream"); + +test("source transport refuses non-public resolution before any HTTP request", async () => { + let requests = 0; + for (const address of ["127.0.0.1", "10.1.2.3", "169.254.169.254", "172.16.1.1", "192.168.1.1", "100.64.1.1", "224.0.0.1", "::1", "::ffff:127.0.0.1"]) { + assert.equal(isPublicAddress(address), false); + const fetch = createSourceFetch("https://example.com", { resolve4: async () => [address], request() { requests++; } }); + await assert.rejects(fetch("https://example.com/v1/snapshot.json"), /non-public/); + } + assert.equal(requests, 0); + assert.equal(isPublicAddress("1.1.1.1"), true); +}); + +test("static resources cannot redirect requests to unrelated origins or arbitrary paths", async () => { + let resolutions = 0; + const fetch = createSourceFetch("https://example.com", { resolve4: async () => { resolutions++; return ["1.1.1.1"]; } }); + for (const value of ["https://other.com/v1/snapshot.json", "https://example.com/admin", "https://example.com/assets/%2e%2e/secret", "https://example.com/v1/snapshot.json?token=secret", "https://user:pass@example.com/v1/snapshot.json"]) await assert.rejects(fetch(value)); + assert.equal(resolutions, 0); +}); + +test("the HTTPS connection uses the checked address without a second DNS lookup or credentials", async () => { + let resolutions = 0; + const fetch = createSourceFetch("https://example.com", { + resolve4: async () => { resolutions++; return resolutions === 1 ? ["1.1.1.1"] : ["127.0.0.1"]; }, + request(url, options, callback) { + assert.equal(url.hostname, "example.com"); + assert.equal(options.agent, false); + assert.equal(options.headers.cookie, undefined); + assert.equal(options.headers.authorization, undefined); + options.lookup("example.com", { all: true }, (error, addresses) => { + assert.equal(error, null); + assert.deepEqual(addresses, [{ address: "1.1.1.1", family: 4 }]); + }); + const response = Readable.from([Buffer.from("synthetic metadata")]); + response.statusCode = 200; response.headers = {}; + callback(response); + return new EventEmitter(); + }, + }); + assert.equal(await (await fetch("https://example.com/v1/snapshot.json")).text(), "synthetic metadata"); + assert.equal(resolutions, 1); +}); diff --git a/electron/plugins/sourceIdentity.cjs b/electron/plugins/sourceIdentity.cjs new file mode 100644 index 000000000..99f9f57b6 --- /dev/null +++ b/electron/plugins/sourceIdentity.cjs @@ -0,0 +1,44 @@ +"use strict"; + +const { createHash } = require("node:crypto"); +const { isIP } = require("node:net"); + +const OFFICIAL_ORIGIN = "https://plugins.netcatty.app"; +const OFFICIAL_SOURCE = Object.freeze({ id: "official", kind: "official", name: "Netcatty marketplace", origin: OFFICIAL_ORIGIN }); +const LOCAL_SOURCE = Object.freeze({ id: "local", kind: "local", name: "Local import", origin: null }); +const hash = (value) => createHash("sha256").update(value).digest("hex"); + +// Source identity is host-owned. Neither a manifest nor a catalog supplies kind/id. +function canonicalSourceOrigin(value) { + if (typeof value !== "string" || value.length > 2048 || /[\s\\%?#]/u.test(value)) throw new Error("Use a public HTTPS origin without credentials, query or fragment"); + const url = new URL(value); + if (url.protocol !== "https:" || url.username || url.password || url.port + || !["/", "/v1/snapshot.json"].includes(url.pathname)) throw new Error("Use an HTTPS origin or its /v1/snapshot.json endpoint"); + const hostname = url.hostname.toLowerCase(); + if (isIP(hostname) || hostname.includes(":") || !hostname.includes(".") || hostname.endsWith(".") + || /(?:^|\.)(?:localhost|local|internal|invalid|test)$/u.test(hostname)) throw new Error("Market sources must use a public DNS hostname"); + // Explicitly reject textual credentials/normalization tricks before canonicalizing case. + if (!/^https:\/\/[^/@]+(?:\/|\/v1\/snapshot\.json)?$/iu.test(value)) throw new Error("Invalid market source address"); + return url.origin; +} + +function thirdPartySource(name, address) { + if (typeof name !== "string" || !name.trim() || name.length > 100 || /[\u0000-\u001f\u007f]/u.test(name)) throw new Error("Source name must contain 1-100 printable characters"); + const origin = canonicalSourceOrigin(address); + if (origin === OFFICIAL_ORIGIN) throw new Error("The official source is already built in"); + return Object.freeze({ id: `third-party:${hash(origin)}`, kind: "third-party", name: name.trim(), origin }); +} + +function assertSource(source) { + if (!source || typeof source !== "object") throw new Error("Missing host source identity"); + const trusted = source.id === "official" ? OFFICIAL_SOURCE : source.id === "local" ? LOCAL_SOURCE : thirdPartySource(source.name, source.origin); + if (["id", "kind", "origin"].some((key) => trusted[key] !== source[key])) throw new Error("Invalid host source identity"); + return { ...trusted }; +} + +function privateOwner(source, pluginId) { + if (typeof pluginId !== "string" || !/^[a-z0-9][a-z0-9.-]{1,127}$/u.test(pluginId)) throw new Error("Invalid plugin identity"); + return `source:${hash(assertSource(source).id)}:${pluginId}`; +} + +module.exports = { OFFICIAL_SOURCE, LOCAL_SOURCE, canonicalSourceOrigin, thirdPartySource, assertSource, privateOwner }; diff --git a/electron/plugins/sourceIdentity.test.cjs b/electron/plugins/sourceIdentity.test.cjs new file mode 100644 index 000000000..60a233d81 --- /dev/null +++ b/electron/plugins/sourceIdentity.test.cjs @@ -0,0 +1,27 @@ +"use strict"; +const test = require("node:test"); +const assert = require("node:assert/strict"); +const { OFFICIAL_SOURCE, LOCAL_SOURCE, canonicalSourceOrigin, thirdPartySource, assertSource, privateOwner } = require("./sourceIdentity.cjs"); + +test("renames preserve source identity; public plugin IDs do not define private ownership", () => { + const a = thirdPartySource("First", "https://EXAMPLE.com/v1/snapshot.json"); + const renamed = thirdPartySource("Renamed", "https://example.com/"); + assert.equal(a.id, renamed.id); + const owners = [a, thirdPartySource("Other", "https://other.example.com"), OFFICIAL_SOURCE, LOCAL_SOURCE].map((source) => privateOwner(source, "example.plugin")); + assert.equal(new Set(owners).size, 4); + assert.equal(privateOwner(a, "example.plugin"), privateOwner(renamed, "example.plugin")); + assert.throws(() => privateOwner(a, owners[0])); +}); + +test("remote metadata cannot promote a source to official or local", () => { + const source = thirdPartySource("Netcatty", "https://example.com"); + for (const kind of ["official", "local"]) assert.throws(() => assertSource({ ...source, kind })); + assert.throws(() => assertSource({ ...source, id: "official" })); + assert.throws(() => thirdPartySource("Mirror", "https://plugins.netcatty.app")); +}); + +test("source addresses exclude secrets, ambiguous paths and local literals", () => { + for (const url of ["http://example.com", "https://user:secret@example.com", "https://example.com?token=x", "https://example.com/#x", "https://127.0.0.1", "https://[::1]", "https://localhost", "https://a.local", "https://example.com:8443", "https://example.com/../v1/snapshot.json", "https://example.com/%2e", "https://example.com\\@other.com", "https://example.com."]) { + assert.throws(() => canonicalSourceOrigin(url), url); + } +}); diff --git a/electron/plugins/sourceIsolation.test.cjs b/electron/plugins/sourceIsolation.test.cjs new file mode 100644 index 000000000..76f1df0f4 --- /dev/null +++ b/electron/plugins/sourceIsolation.test.cjs @@ -0,0 +1,112 @@ +"use strict"; +const test = require("node:test"); +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const { PluginDatabase } = require("./database.cjs"); +const { thirdPartySource, LOCAL_SOURCE } = require("./sourceIdentity.cjs"); +const { PluginSyncSidecarService } = require("./pluginSyncSidecarService.cjs"); +const { settingsSidecarKey } = require("./pluginSyncSidecarHelpers.cjs"); +const id = "example.plugin"; +const first = thirdPartySource("First", "https://first.example.com"); +const second = thirdPartySource("Second", "https://second.example.com"); +function install(db, source) { + db.installVersion({ pluginId: id, version: "1.0.0", manifest: {}, archiveSha256: "a".repeat(64), packageRelativePath: "example.plugin/1.0.0", source }); +} +test("schema-4 local provenance survives upgrade and uninstall until explicit reset", (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-source-upgrade-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const file = path.join(root, "db.sqlite"); + let db = new PluginDatabase(file); + install(db, LOCAL_SOURCE); + db.setSetting(id, "private", "application", "application", "retained"); + db.db.exec("DROP TABLE plugin_source_bindings; PRAGMA user_version = 4"); + db.close(); + db = new PluginDatabase(file); + t.after(() => db.close()); + db.removePlugin(id); + assert.equal(db.getRetainedPluginSource(id).id, "local"); + assert.throws(() => install(db, first), /source differs/); + assert.equal(db.getSetting(id, "private", "application", "application"), "retained"); + db.clearUninstalledSourceData(id, "local"); + install(db, first); + assert.equal(db.getSetting(id, "private", "application", "application"), undefined); +}); + +test("failed provenance backfill does not publish the new schema version", (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-source-upgrade-failure-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const file = path.join(root, "db.sqlite"); + const db = new PluginDatabase(file); + t.after(() => db.close()); + install(db, LOCAL_SOURCE); + db.db.exec("DELETE FROM plugin_source_bindings; PRAGMA user_version = 5; CREATE TRIGGER fail_source_backfill BEFORE INSERT ON plugin_source_bindings BEGIN SELECT RAISE(ABORT, 'synthetic backfill failure'); END;"); + assert.throws(() => new PluginDatabase(file, { database: db.db }), /synthetic backfill failure/); + assert.equal(db.db.prepare("PRAGMA user_version").get().user_version, 5); + db.db.exec("DROP TRIGGER fail_source_backfill"); + new PluginDatabase(file, { database: db.db }); + db.removePlugin(id); + assert.equal(db.getRetainedPluginSource(id).id, "local"); + assert.throws(() => install(db, first), /source differs/); +}); +test("same ID cannot change source during install, uninstall or database restart without explicit private reset", (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-source-isolation-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const file = path.join(root, "db.sqlite"); + let db = new PluginDatabase(file); + install(db, first); + db.setValue(id, "key", "old KV"); + assert.deepEqual(db.listKeys(id), ["key"]); + db.setSetting(id, "greeting", "application", "application", "old setting"); + db.setViewState(id, "view", "self", { private: true }); + db.upsertPermissionGrant({ pluginId: id, permission: "views", resource: "self", resourceKind: "exact", declarationHash: "same-code" }); + db.upsertSecret({ pluginId: id, key: "secret", secretRef: "old-ref", ciphertext: Buffer.from("ciphertext") }); + db.setSyncSidecar(id, "account_baseline", "account", "old baseline"); + assert.equal(db.getSecretByRef(id, "old-ref").pluginId, id); + assert.deepEqual(db.listPluginIdsWithSecretKeyPrefix("secret"), [id], "host provider recovery receives the current public plugin ID, not its opaque storage owner"); + assert.equal(db.listPermissionGrants(id)[0].pluginId, id); + assert.throws(() => install(db, second), /source differs/); + assert.throws(() => db.clearUninstalledSourceData(id, first.id), /Uninstall/); + db.removePlugin(id); + db.close(); + db = new PluginDatabase(file); + t.after(() => db.close()); + assert.throws(() => install(db, second), /source differs/); + assert.throws(() => install(db, LOCAL_SOURCE), /source differs/); + assert.throws(() => db.clearUninstalledSourceData(id, second.id), /changed/); + db.clearUninstalledSourceData(id, first.id); + install(db, second); + assert.equal(db.getActivePlugin(id).source.id, second.id); + assert.equal(db.getValue(id, "key"), undefined); + assert.equal(db.getSetting(id, "greeting", "application", "application"), undefined); + assert.equal(db.getViewState(id, "view", "self"), undefined); + assert.deepEqual(db.listPermissionGrants(id), []); + assert.equal(db.getSecretByRef(id, "old-ref"), null); + assert.equal(db.getSyncSidecar(id, "account_baseline", "account"), undefined); +}); + +test("old-source cloud settings remain orphaned and cannot hydrate a new source", async (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-source-sync-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const db = new PluginDatabase(path.join(root, "db.sqlite")); + t.after(() => db.close()); + install(db, first); + const oldOwner = db.privateOwner(id); + db.removePlugin(id); + db.clearUninstalledSourceData(id, first.id); + install(db, second); + const calls = []; + const service = new PluginSyncSidecarService({ database: db, contributionService: { + snapshot: () => ({ plugins: [{ id, settings: [{ id: "greeting", scope: "application", sync: true }] }] }), + updateSetting: (...args) => calls.push(args), + } }); + const entry = { pluginId: oldOwner, kind: "settings", key: settingsSidecarKey("greeting", "application", "application"), value: "old remote data", updatedAt: 1000 }; + await service.applyFromSync({ version: 1, entries: [entry] }); + await service.hydrateInstalledPluginSettings(id); + assert.deepEqual(calls, []); + assert.equal(db.getSetting(id, "greeting", "application", "application"), undefined); + await service.applyFromSync({ version: 1, entries: [{ ...entry, pluginId: db.privateOwner(id), value: "new source" }] }); + assert.equal(calls[0][0], id); + assert.equal(db.getSetting(id, "greeting", "application", "application"), "new source"); +}); diff --git a/electron/plugins/sourceRegistry.cjs b/electron/plugins/sourceRegistry.cjs new file mode 100644 index 000000000..c2323dce7 --- /dev/null +++ b/electron/plugins/sourceRegistry.cjs @@ -0,0 +1,62 @@ +"use strict"; + +const { OFFICIAL_SOURCE, thirdPartySource, assertSource } = require("./sourceIdentity.cjs"); +const PREFERENCE_KEY = "market-sources-v1"; + +// Only this host service creates source records. Remote catalogs cannot mutate them. +class PluginSourceRegistry { + constructor(database) { this.database = database; } + #read() { + const row = this.database.db.prepare("SELECT value_json FROM plugin_host_preferences WHERE key = ?").get(PREFERENCE_KEY); + if (!row) return []; + const values = JSON.parse(row.value_json); + if (!Array.isArray(values) || values.length > 32) throw new Error("Invalid saved plugin sources"); + const ids = new Set(); + return values.map((value) => { + const source = assertSource(value); + if (source.kind !== "third-party" || ids.has(source.id) || typeof value.enabled !== "boolean") throw new Error("Invalid saved plugin source"); + ids.add(source.id); + return { ...source, enabled: value.enabled }; + }); + } + #write(values) { + this.database.db.prepare("INSERT INTO plugin_host_preferences(key,value_json,updated_at) VALUES(?,?,?) ON CONFLICT(key) DO UPDATE SET value_json=excluded.value_json,updated_at=excluded.updated_at") + .run(PREFERENCE_KEY, JSON.stringify(values), this.database.clock()); + } + list() { return [{ ...OFFICIAL_SOURCE, enabled: true }, ...this.#read()]; } + get(id) { + const source = this.list().find((item) => item.id === id); + if (!source || !source.enabled) throw new Error("This market source was removed or disabled; no alternate source will be used"); + return source; + } + add(name, address) { + const source = thirdPartySource(name, address); + this.database.transaction(() => { + const values = this.#read(); + if (values.some((item) => item.id === source.id)) throw new Error("This market source already exists"); + if (values.length >= 32) throw new Error("At most 32 third-party sources are supported"); + this.#write([...values, { ...source, enabled: true }]); + }); + return this.get(source.id); + } + update(id, name, enabled) { + if (typeof enabled !== "boolean") throw new Error("Source enabled state must be boolean"); + this.database.transaction(() => { + const values = this.#read(); + const index = values.findIndex((source) => source.id === id); + if (index < 0) throw new Error("Third-party source does not exist"); + values[index] = { ...thirdPartySource(name, values[index].origin), enabled }; + this.#write(values); + }); + return this.list().find((source) => source.id === id); + } + remove(id) { + this.database.transaction(() => { + const values = this.#read(); + if (!values.some((source) => source.id === id)) throw new Error("Third-party source does not exist"); + this.#write(values.filter((source) => source.id !== id)); + }); + // Package lifetime and optional disabling belong to serialized PluginManager. + } +} +module.exports = { PluginSourceRegistry }; diff --git a/electron/plugins/sourceRegistry.test.cjs b/electron/plugins/sourceRegistry.test.cjs new file mode 100644 index 000000000..f1e7d9850 --- /dev/null +++ b/electron/plugins/sourceRegistry.test.cjs @@ -0,0 +1,33 @@ +"use strict"; +const test = require("node:test"); +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const { PluginDatabase } = require("./database.cjs"); +const { PluginSourceRegistry } = require("./sourceRegistry.cjs"); + +test("sources persist, rename without changing identity, and fail closed when disabled or removed", (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-sources-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const file = path.join(root, "db.sqlite"); + let db = new PluginDatabase(file); + let registry = new PluginSourceRegistry(db); + assert.equal(registry.list().length, 1); + const source = registry.add("Example", "https://example.com"); + assert.throws(() => registry.add("Duplicate", "https://example.com/v1/snapshot.json")); + registry.update(source.id, "Renamed", false); + assert.throws(() => registry.get(source.id), /removed or disabled/); + db.close(); + db = new PluginDatabase(file); + t.after(() => db.close()); + registry = new PluginSourceRegistry(db); + assert.equal(registry.list()[1].name, "Renamed"); + registry.update(source.id, "Again", true); + assert.equal(registry.get(source.id).origin, source.origin); + registry.remove(source.id); + assert.throws(() => registry.get(source.id), /removed or disabled/); + assert.throws(() => registry.remove("official")); + assert.throws(() => registry.update("official", "Impersonated", false)); + assert.equal(registry.get("official").origin, "https://plugins.netcatty.app"); +}); diff --git a/electron/plugins/staticDistribution.test.cjs b/electron/plugins/staticDistribution.test.cjs new file mode 100644 index 000000000..913e9c472 --- /dev/null +++ b/electron/plugins/staticDistribution.test.cjs @@ -0,0 +1,106 @@ +"use strict"; +const assert = require("node:assert/strict"); +const test = require("node:test"); +const { assertDownloadUrl, fetchBounded, validateCatalog } = require("./catalogService.cjs"); +const { RegistryCatalogService, REGISTRY_URL } = require("./registryCatalogService.cjs"); +const { fetchVerified, assertAsset } = require("./distributionSnapshot.cjs"); +const { read, digest, catalog, delivery, realFiles, makeFiles, responseFor } = require("./fixtures/staticDistributionFixture.cjs"); + +test("exact registry PR3 bootstrap hashes and all README/icon assets verify without GitHub requests", async () => { + assert.equal(digest(read("snapshot.json")), "2878885057a01585e34897c226bcfd81615345d843ea94297980de7e397b4617"); + assert.equal(digest(read("delivery.json")), "53e5189d2cb58a02826931d5d6321ad3e556b924ef80d38636dc9e66a7df8c55"); + const requests = []; const files = realFiles(); + const fetch = async (url, options) => { + requests.push(url); assert.equal(new URL(url).origin, "https://plugins.netcatty.app"); + assert.equal(options.credentials, "omit"); assert.equal(options.redirect, "manual"); + return responseFor(files, url); + }; + const service = new RegistryCatalogService({ fetch }); + const snapshot = await service.list(); + assert.equal(snapshot.error, null); assert.equal(snapshot.source, "registry"); + assert.equal(requests.length, 4); assert.equal(requests[0], REGISTRY_URL); + for (const entry of snapshot.entries) { + const resource = delivery.plugins.find((item) => item.id === entry.id); + assert.equal(await service.readme(entry.id, entry.selectionToken), read(resource.readme.path.slice(1)).toString()); + for (const icon of [resource.iconLight, resource.iconDark]) if (icon) { + assertAsset(icon, ["png", "webp"]); + const bytes = await fetchVerified(icon, fetch); + assert.equal(bytes.length, icon.size); assert.equal(digest(bytes), icon.sha256); + } + assert.equal(entry.artifact, undefined); + assert.equal(resource.avatar, null); assert.equal(resource.artifact, null); + } + assert.ok(requests.every((url) => !/github/u.test(url))); +}); + +test("GitHub, tracking and noncanonical URLs are rejected before any upstream request", async () => { + for (const url of [ + "https://api.github.com/repos/a/b", "https://raw.githubusercontent.com/a/b/main/README.md", + "https://avatars.githubusercontent.com/u/1", "https://github.com/a/b/releases/download/v1/a.ncpkg", + "https://release-assets.githubusercontent.com/a", "https://objects.githubusercontent.com/a", + "https://plugins.netcatty.app.attacker.invalid/a", "https://plugins.netcatty.app@attacker.invalid/a", + "http://plugins.netcatty.app/a", "https://plugins.netcatty.app/a?track=1", "https://plugins.netcatty.app/a#fragment", + "https://plugins.netcatty.app/a/../b", "https://plugins.netcatty.app/%2e%2e/b", "https://plugins.netcatty.app/\ta", + ]) { + assert.throws(() => assertDownloadUrl(url)); + assert.throws(() => validateCatalog([{ ...catalog[0], artifact: { url, sha256: "a".repeat(64) } }])); + await assert.rejects(fetchBounded(url, 1024, () => assert.fail("invalid source must not be requested"))); + } +}); + +test("official responses never redirect to GitHub or another official path", async () => { + for (const location of ["https://github.com/a", "https://raw.githubusercontent.com/a/b/main/catalog.json", "https://plugins.netcatty.app/another.json"]) { + const requests = []; + await assert.rejects(fetchBounded(REGISTRY_URL, 1024, async (url) => { + requests.push(url); return new Response(null, { status: 302, headers: { location } }); + }), /redirects/); + assert.deepEqual(requests, [REGISTRY_URL]); + } +}); + +test("cross-document mismatches, withdrawn versions and unsupported assets preserve the complete good cache", async () => { + let files = realFiles(); const service = new RegistryCatalogService({ fetch: async (url) => responseFor(files, url) }); + const good = await service.list(); const goodResources = service.resources; + const mutations = [ + (index, sidecar) => { sidecar.registryCommit = "a".repeat(40); }, + (index, sidecar) => { sidecar.plugins[0].commit = "a".repeat(40); }, + (index, sidecar) => { sidecar.plugins.push(sidecar.plugins[0]); }, + (index, sidecar) => { sidecar.plugins.pop(); }, + (index, sidecar) => { sidecar.plugins[0].readme.path = "https://raw.githubusercontent.com/a/b/main/README.md"; }, + (index, sidecar) => { sidecar.plugins[0].readme.path = `/assets/${sidecar.plugins[0].readme.sha256}.png`; }, + (index, sidecar) => { sidecar.plugins[0].iconLight.path = `/assets/${sidecar.plugins[0].iconLight.sha256}.md`; }, + (index, sidecar) => { sidecar.plugins[0].avatar = { path: "/assets/avatar.png" }; }, + (index, sidecar) => { sidecar.plugins[0].artifact = { path: "/assets/package.ncpkg" }; }, + (index) => { index.plugins[0].versions[0].withdrawal = { at: "2026-10-26T00:00:00Z", reason: "synthetic withdrawal", advisory: "https://github.com/example/advisory" }; }, + (index) => { index.plugins[0].versions[0].entry.description += " mismatch"; }, + (index) => { index.plugins[0].current = "9.0.0"; }, + (index) => { index.plugins.push(index.plugins[0]); }, + (index, sidecar) => { sidecar.unknown = true; }, + ]; + for (const mutate of mutations) { + files = makeFiles(catalog, mutate); + // Preserve the pointer's trusted registry identity when testing delivery mismatch. + const pointer = JSON.parse(files.get("/v1/snapshot.json")); pointer.registryCommit = delivery.registryCommit; + files.set("/v1/snapshot.json", Buffer.from(JSON.stringify(pointer))); + const rejected = await service.list(); + assert.equal(rejected.source, "cached"); assert.ok(rejected.error); + assert.deepEqual(rejected.entries, good.entries); assert.equal(service.resources, goodResources); + } +}); + +test("pointer/document/resource byte mismatches and partial availability never publish partial state", async () => { + let files = realFiles(); const service = new RegistryCatalogService({ fetch: async (url) => responseFor(files, url) }); + const good = await service.list(); + const pointer = JSON.parse(read("snapshot.json")); + for (const name of ["catalog", "index", "delivery"]) { + files = realFiles(); files.set(pointer[name].path, Buffer.from("{}")); + const rejected = await service.list(); assert.equal(rejected.source, "cached"); assert.deepEqual(rejected.entries, good.entries); + files = realFiles(); files.delete(pointer[name].path); + assert.deepEqual((await service.list()).entries, good.entries); + } + files = realFiles(); const altered = structuredClone(pointer); altered.catalog.path = "/catalog.json"; + files.set("/v1/snapshot.json", Buffer.from(JSON.stringify(altered))); + assert.match((await service.list()).error, /resource reference/); + files = realFiles(); files.set(delivery.plugins[0].readme.path, Buffer.from("x".repeat(delivery.plugins[0].readme.size))); + await assert.rejects(service.readme(good.entries[0].id, good.entries[0].selectionToken), /SHA-256 mismatch/); +}); diff --git a/electron/plugins/streamRouter.cjs b/electron/plugins/streamRouter.cjs index b9cc88569..b22ff7bfa 100644 --- a/electron/plugins/streamRouter.cjs +++ b/electron/plugins/streamRouter.cjs @@ -158,6 +158,8 @@ class PluginStreamRouter { this.outgoing.delete(frame.streamId); for (const pending of outgoing.queue) pending.reject(new Error(`Plugin stream cancelled: ${frame.streamId}`)); outgoing.queue.length = 0; + outgoing.queuedBytes = 0; + this.#notifyOutgoingClosed(outgoing, "cancel"); return; } const state = this.incoming.get(frame.streamId); @@ -233,7 +235,8 @@ class PluginStreamRouter { state.onClose = handlers.onClose; } - async openOutgoing(streamId, windowBytes) { + async openOutgoing(streamId, windowBytes, options = {}) { + if (options.onClose !== undefined && typeof options.onClose !== "function") throw new TypeError("Stream onClose must be a function"); if ( this.closed || this.outgoing.has(streamId) @@ -268,6 +271,7 @@ class PluginStreamRouter { queuedBytes: 0, closed: false, terminalKind: null, + onClose: options.onClose, }; this.outgoing.set(streamId, state); try { @@ -347,6 +351,13 @@ class PluginStreamRouter { for (const pending of state.queue) pending.reject(error); state.queue.length = 0; state.queuedBytes = 0; + this.#notifyOutgoingClosed(state, error); + } + + #notifyOutgoingClosed(state, reason) { + if (state.closeNotified) return; + state.closeNotified = true; + try { state.onClose?.(reason); } catch {} } #finishOutgoing(state, kind) { @@ -373,6 +384,7 @@ class PluginStreamRouter { ) { this.outgoing.delete(state.streamId); } + this.#notifyOutgoingClosed(state, kind); } } @@ -413,6 +425,7 @@ class PluginStreamRouter { for (const state of this.outgoing.values()) { state.closed = true; for (const pending of state.queue) pending.reject(error); + this.#notifyOutgoingClosed(state, error); } this.outgoing.clear(); for (const state of this.incoming.values()) { diff --git a/electron/plugins/utilityPluginRuntime.cjs b/electron/plugins/utilityPluginRuntime.cjs index 7abe63c80..651a5b873 100644 --- a/electron/plugins/utilityPluginRuntime.cjs +++ b/electron/plugins/utilityPluginRuntime.cjs @@ -208,9 +208,9 @@ class UtilityPluginRuntime { this.router.notify(method, params); } - openStream(streamId, windowBytes) { + openStream(streamId, windowBytes, options) { if (!this.router) return Promise.reject(new Error("Plugin utility runtime is not connected")); - return this.router.streams.openOutgoing(streamId, windowBytes); + return this.router.streams.openOutgoing(streamId, windowBytes, options); } attachTerminalInterceptor(descriptor, port) { diff --git a/electron/preload/api.cjs b/electron/preload/api.cjs index 68c1f4eb6..ff2a37d20 100644 --- a/electron/preload/api.cjs +++ b/electron/preload/api.cjs @@ -99,9 +99,15 @@ function createPreloadApi(ctx) { with (ctx) { return { getPluginRuntimeStatus: () => ipcRenderer.invoke("netcatty:plugins:status"), - listPluginCatalog: () => ipcRenderer.invoke("netcatty:plugins:catalog"), - getPluginCatalogReadme: (id, selectionToken) => ipcRenderer.invoke("netcatty:plugins:catalog-readme", { id, selectionToken }), - installCatalogPlugin: (id, selectionToken) => ipcRenderer.invoke("netcatty:plugins:catalog-install", { id, selectionToken }), + getPluginSourceBinding: (pluginId) => ipcRenderer.invoke("netcatty:plugins:source-binding", { pluginId }), + resetPluginSource: (pluginId, expectedSourceId) => ipcRenderer.invoke("netcatty:plugins:reset-source", { pluginId, expectedSourceId }), + listPluginSources: () => ipcRenderer.invoke("netcatty:plugins:sources"), + addPluginSource: (source) => ipcRenderer.invoke("netcatty:plugins:add-source", source), + updatePluginSource: (source) => ipcRenderer.invoke("netcatty:plugins:update-source", source), + removePluginSource: (id, disablePlugins) => ipcRenderer.invoke("netcatty:plugins:remove-source", { id, disablePlugins }), + listPluginCatalog: (sourceId) => ipcRenderer.invoke("netcatty:plugins:catalog", { sourceId }), + getPluginCatalogReadme: (id, selectionToken, sourceId) => ipcRenderer.invoke("netcatty:plugins:catalog-readme", { id, selectionToken, sourceId }), + installCatalogPlugin: (id, selectionToken, sourceId, acceptedSourceId) => ipcRenderer.invoke("netcatty:plugins:catalog-install", { id, selectionToken, sourceId, acceptedSourceId }), setPluginInteractionReady: (ready) => ipcRenderer.invoke("netcatty:plugins:interaction-ready", { ready }), respondPluginInteraction: (response) => ipcRenderer.invoke("netcatty:plugins:interaction-response", response), onPluginInteraction: (callback) => { diff --git a/examples/plugins/database-minimal/browser.js b/examples/plugins/database-minimal/browser.js new file mode 100644 index 000000000..63c6f7fb3 --- /dev/null +++ b/examples/plugins/database-minimal/browser.js @@ -0,0 +1,34 @@ +import { CancellationTokenSource } from "@netcatty/plugin-sdk"; +import { queryExample } from "./protocol.mjs"; +import { endpoint } from "./fixture-config.mjs"; + +export default { + activate(context) { + let pending; + const register = (suffix, handler) => context.subscriptions.add(context.commands.registerCommand( + `com.netcatty.database-minimal.${suffix}`, handler, + )); + const cancel = () => { pending?.cancel(); return { cancelled: true }; }; + register("cancel", cancel); + register("endpoint", () => ({ endpoint })); + context.subscriptions.add({ dispose: cancel }); + register("query", async (args) => { + if (pending) throw new Error("An example connection is already active"); + if (!args || Array.isArray(args) || Object.keys(args).some((key) => !["username", "password"].includes(key)) + || typeof args.username !== "string" || typeof args.password !== "string") throw new Error("Enter disposable fixture credentials"); + const cancellation = new CancellationTokenSource(); + pending = cancellation; + let connection; + try { + connection = await context.network.connect({ endpoint }, cancellation.token); + return await queryExample({ read: () => connection.readable.read(), write: (bytes) => connection.writable.write(bytes), + close: () => connection.close() }, args.username, args.password); + } finally { + args.password = ""; + await connection?.close().catch(() => {}); + cancellation.dispose(); + pending = undefined; + } + }); + }, +}; diff --git a/examples/plugins/database-minimal/fixture-config.mjs b/examples/plugins/database-minimal/fixture-config.mjs new file mode 100644 index 000000000..28c081973 --- /dev/null +++ b/examples/plugins/database-minimal/fixture-config.mjs @@ -0,0 +1 @@ +export const endpoint = "tcp://database-fixture.invalid:3306"; diff --git a/examples/plugins/database-minimal/netcatty.plugin.json b/examples/plugins/database-minimal/netcatty.plugin.json new file mode 100644 index 000000000..d14dbce3e --- /dev/null +++ b/examples/plugins/database-minimal/netcatty.plugin.json @@ -0,0 +1,26 @@ +{ + "manifestVersion": 1, + "id": "com.netcatty.database-minimal", + "name": "database-minimal", + "displayName": "Disposable database example", + "description": "Connect to one prepared synthetic fixture and read one row.", + "version": "0.1.0", + "publisher": "netcatty", + "license": "GPL-3.0-or-later", + "engines": { "netcatty": ">=0.0.0", "api": ">=0.1.0-internal.1 <0.2.0" }, + "features": { "required": ["network.byte-streams"] }, + "main": { "browser": "browser.js" }, + "activationEvents": ["onCommand:com.netcatty.database-minimal.query", "onView:com.netcatty.database-minimal.panel"], + "permissions": { + "required": ["commands", "views"], + "optional": [{ "permission": "network.stream", "resources": ["tcp://database-fixture.invalid:3306"], "reason": "Connect only to the prepared disposable fixture." }] + }, + "contributes": { + "commands": [ + { "id": "com.netcatty.database-minimal.query", "title": "Read one synthetic database row" }, + { "id": "com.netcatty.database-minimal.cancel", "title": "Cancel example connection" }, + { "id": "com.netcatty.database-minimal.endpoint", "title": "Show example endpoint" } + ], + "views": [{ "id": "com.netcatty.database-minimal.panel", "title": "Disposable database example", "location": "modal", "entry": "panel.html" }] + } +} diff --git a/examples/plugins/database-minimal/panel.css b/examples/plugins/database-minimal/panel.css new file mode 100644 index 000000000..9cffda0a6 --- /dev/null +++ b/examples/plugins/database-minimal/panel.css @@ -0,0 +1 @@ +:root{color-scheme:dark light;font:14px system-ui,sans-serif;color:hsl(var(--foreground,210 20% 90%));background:hsl(var(--background,220 15% 12%))}*{box-sizing:border-box}body{margin:0}main{max-width:640px;padding:24px;margin:auto}h1{font-size:24px}.eyebrow{font-size:11px;letter-spacing:.1em;opacity:.7}p{line-height:1.5}#endpoint,pre{overflow-wrap:anywhere;white-space:pre-wrap}label{display:block;margin:16px 0 6px}input{width:100%;padding:10px;border:1px solid hsl(var(--border,220 10% 35%));border-radius:6px;background:hsl(var(--background,220 15% 12%));color:inherit}.actions{display:flex;flex-wrap:wrap;gap:10px;margin:20px 0}button{padding:10px 16px;border:1px solid hsl(var(--border,220 10% 35%));border-radius:6px;color:inherit;background:hsl(var(--secondary,220 12% 22%));cursor:pointer}button:disabled{opacity:.5;cursor:default}input:focus-visible,button:focus-visible{outline:2px solid hsl(var(--primary,210 90% 60%));outline-offset:2px}pre{padding:14px;border:1px solid hsl(var(--border,220 10% 35%));border-radius:6px;min-height:80px} diff --git a/examples/plugins/database-minimal/panel.html b/examples/plugins/database-minimal/panel.html new file mode 100644 index 000000000..93aa1056f --- /dev/null +++ b/examples/plugins/database-minimal/panel.html @@ -0,0 +1,10 @@ + +Disposable database example +

NETCATTY PLUGIN EXAMPLE

Read one synthetic row

+

This example connects only to its prepared disposable test server. Enter the fixture account. Credentials stay in this session.

+

Loading prepared endpoint…

+ + +
+
Ready for a disposable fixture.
+
diff --git a/examples/plugins/database-minimal/panel.js b/examples/plugins/database-minimal/panel.js new file mode 100644 index 000000000..cba90ac97 --- /dev/null +++ b/examples/plugins/database-minimal/panel.js @@ -0,0 +1,35 @@ +/* global window, document */ +"use strict"; +const username = document.getElementById("username"); +const password = document.getElementById("password"); +const query = document.getElementById("query"); +const cancel = document.getElementById("cancel"); +const result = document.getElementById("result"); +const command = (suffix, args) => window.netcattyView.executeCommand(`com.netcatty.database-minimal.${suffix}`, args); +window.netcattyView.onDidChangeEnvironment((environment) => { + document.documentElement.style.colorScheme = environment.theme === "light" ? "light" : "dark"; + for (const name of ["--background", "--foreground", "--muted", "--muted-foreground", "--border", "--primary", "--primary-foreground"]) { + const value = environment.themeTokens?.[name]; + if (typeof value === "string" && value.length <= 96) document.documentElement.style.setProperty(name, value); + else document.documentElement.style.removeProperty(name); + } +}); +void command("endpoint").then((value) => { document.getElementById("endpoint").textContent = value.endpoint; }); +document.getElementById("form").addEventListener("submit", async (event) => { + event.preventDefault(); + query.disabled = true; + cancel.disabled = false; + result.textContent = "Connecting to the disposable fixture…"; + const credentials = { username: username.value, password: password.value }; + password.value = ""; + try { + const response = await command("query", credentials); + result.textContent = JSON.stringify(response, null, 2); + } catch { result.textContent = "Connection or read failed. Check the fixture, exact endpoint grant, and session credentials."; } + finally { credentials.password = ""; query.disabled = false; cancel.disabled = true; } +}); +cancel.addEventListener("click", async () => { + cancel.disabled = true; + try { await command("cancel"); result.textContent = "Example connection cancelled."; } + catch { result.textContent = "Could not cancel the example connection."; } +}); diff --git a/examples/plugins/database-minimal/prepare.mjs b/examples/plugins/database-minimal/prepare.mjs new file mode 100644 index 000000000..e8701c23e --- /dev/null +++ b/examples/plugins/database-minimal/prepare.mjs @@ -0,0 +1,41 @@ +import fs from "node:fs/promises"; +import process from "node:process"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { buildPluginPackage } from "@netcatty/plugin-cli"; +import { build } from "esbuild"; +import { createRequire } from "node:module"; + +const require = createRequire(import.meta.url); +const { canonicalizeStreamEndpoint, isLocalControlAddress } = require("../../../electron/plugins/byteStreamEndpoint.cjs"); +const { isIP } = require("node:net"); +const root = path.dirname(fileURLToPath(import.meta.url)); + +export async function prepareDatabaseExample(targetEndpoint, outputPath) { + const { endpoint, transport, host } = canonicalizeStreamEndpoint(targetEndpoint); + // This preparation tool only targets a disposable private IPv4 fixture. + // The generic host capability has no database restriction or protocol logic. + if (transport !== "tcp" || isIP(host) !== 4 || isLocalControlAddress(host) + || !/^(10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.)/u.test(host)) throw new Error("Use the isolated fixture's private IPv4 TCP endpoint"); + const temporary = await fs.mkdtemp(path.join(path.dirname(outputPath), ".database-example-")); + try { + const manifest = JSON.parse(await fs.readFile(path.join(root, "netcatty.plugin.json"), "utf8")); + manifest.permissions.optional[0].resources = [endpoint]; + await fs.writeFile(path.join(temporary, "netcatty.plugin.json"), `${JSON.stringify(manifest, null, 2)}\n`); + for (const file of ["browser.js", "protocol.mjs", "panel.html", "panel.css", "panel.js"]) await fs.copyFile(path.join(root, file), path.join(temporary, file)); + await fs.writeFile(path.join(temporary, "fixture-config.mjs"), `export const endpoint = ${JSON.stringify(endpoint)};\n`); + const bundle = await build({ entryPoints: [path.join(temporary, "browser.js")], write: false, + bundle: true, platform: "browser", format: "esm", nodePaths: [path.resolve(root, "../../../node_modules")] }); + await fs.writeFile(path.join(temporary, "browser.js"), bundle.outputFiles[0].contents); + await fs.rm(path.join(temporary, "protocol.mjs")); + await fs.rm(path.join(temporary, "fixture-config.mjs")); + return await buildPluginPackage(temporary, outputPath); + } finally { await fs.rm(temporary, { recursive: true, force: true }); } +} + +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + const [endpoint, outputPath] = process.argv.slice(2); + if (!endpoint || !outputPath) throw new Error("Usage: node prepare.mjs tcp://:3306 "); + const result = await prepareDatabaseExample(endpoint, path.resolve(outputPath)); + process.stdout.write(`${JSON.stringify(result)}\n`); +} diff --git a/examples/plugins/database-minimal/protocol.mjs b/examples/plugins/database-minimal/protocol.mjs new file mode 100644 index 000000000..1ebe41941 --- /dev/null +++ b/examples/plugins/database-minimal/protocol.mjs @@ -0,0 +1,163 @@ +// Intentionally limited browser example, not a general database driver. Supports +// protocol 4.1, mysql_native_password, and exactly one fixed text result column. +// The fixture account's server-side SELECT grant enforces access control. +export const READ_QUERY = "SELECT value FROM plugin_demo.example_result LIMIT 1"; +const encoder = new globalThis.TextEncoder(); +const decoder = new globalThis.TextDecoder("utf-8", { fatal: true }); +const MAX_PACKET = 64 * 1024 - 1; +const MAX_TOTAL = 512 * 1024; +const CLIENT_FLAGS = 1 | 4 | 8 | 0x200 | 0x2000 | 0x8000 | 0x80000; + +function reject() { throw new Error("Unsupported or invalid example database response"); } +function concat(...chunks) { + const value = new Uint8Array(chunks.reduce((sum, chunk) => sum + chunk.length, 0)); + let offset = 0; + for (const chunk of chunks) { value.set(chunk, offset); offset += chunk.length; } + return value; +} +function zeroText(text) { return concat(encoder.encode(text), Uint8Array.of(0)); } +function uint32(value) { + const result = new Uint8Array(4); + new DataView(result.buffer).setUint32(0, value, true); + return result; +} + +class Cursor { + constructor(bytes) { this.bytes = bytes; this.offset = 0; } + take(length) { + if (!Number.isInteger(length) || length < 0 || this.offset + length > this.bytes.length) reject(); + const result = this.bytes.subarray(this.offset, this.offset + length); + this.offset += length; + return result; + } + byte() { return this.take(1)[0]; } + short() { const bytes = this.take(2); return bytes[0] | (bytes[1] << 8); } + text() { + const end = this.bytes.indexOf(0, this.offset); + if (end === -1) reject(); + const result = decoder.decode(this.take(end - this.offset)); + this.byte(); + return result; + } + lengthText() { + const marker = this.byte(); + if (marker === 0xfb) return null; + const length = marker < 0xfb ? marker : marker === 0xfc ? this.short() : reject(); + if (length > 4096) reject(); + return decoder.decode(this.take(length)); + } +} + +class Packets { + constructor(stream) { this.stream = stream; this.pending = new Uint8Array(); this.offset = 0; this.total = 0; this.packets = 0; } + async exact(length) { + const result = new Uint8Array(length); + let offset = 0; + while (offset < length) { + if (this.offset === this.pending.length) { + this.pending = await this.stream.read(); + this.offset = 0; + if (!(this.pending instanceof Uint8Array) || !this.pending.length || this.pending.length > 64 * 1024) reject(); + this.total += this.pending.length; + if (this.total > MAX_TOTAL) reject(); + } + const count = Math.min(length - offset, this.pending.length - this.offset); + result.set(this.pending.subarray(this.offset, this.offset + count), offset); + this.offset += count; + offset += count; + } + return result; + } + async read(sequence) { + if (++this.packets > 32) reject(); + const header = await this.exact(4); + const length = header[0] | (header[1] << 8) | (header[2] << 16); + if (!length || length > MAX_PACKET || header[3] !== sequence) reject(); + const payload = await this.exact(length); + // Never display peer-provided errors, which may echo user input or secrets. + if (payload[0] === 0xff) throw new Error("Example database server rejected the request"); + return payload; + } + async write(bytes, sequence) { + if (bytes.length > MAX_PACKET) reject(); + await this.stream.write(concat(Uint8Array.of(bytes.length & 255, (bytes.length >>> 8) & 255, 0, sequence), bytes)); + } +} + +async function authentication(password, nonce) { + if (!password.length) return new Uint8Array(); + const digest = async (bytes) => new Uint8Array(await globalThis.crypto.subtle.digest("SHA-1", bytes)); + const passwordBytes = encoder.encode(password); + let first; + let second; + let third; + try { + first = await digest(passwordBytes); + second = await digest(first); + third = await digest(concat(nonce, second)); + return first.map((byte, index) => byte ^ third[index]); + } finally { + passwordBytes.fill(0); + first?.fill(0); + second?.fill(0); + third?.fill(0); + } +} + +function greeting(bytes) { + const cursor = new Cursor(bytes); + if (cursor.byte() !== 10) reject(); + cursor.text(); + cursor.take(4); + const nonceFirst = cursor.take(8); + if (cursor.byte() !== 0) reject(); + const lower = cursor.short(); + cursor.byte(); + cursor.short(); + const upper = cursor.short(); + const capabilities = lower | (upper << 16); + const authLength = cursor.byte(); + // MariaDB clears bit zero to identify its extended dialect. This example + // sends CLIENT_MYSQL (bit zero) and uses only the common 4.1 protocol. + const required = CLIENT_FLAGS & ~1; + if ((capabilities & required) !== required || authLength !== 21) reject(); + cursor.take(10); + const nonceSecond = cursor.take(13); + if (nonceSecond[12] !== 0 || cursor.text() !== "mysql_native_password") reject(); + return concat(nonceFirst, nonceSecond.subarray(0, 12)); +} + +/** stream is a plugin-owned browser adapter over the generic host byte stream. */ +export async function queryExample(stream, username, sessionPassword) { + if (!/^[A-Za-z0-9_]{1,32}$/u.test(username) || typeof sessionPassword !== "string" || sessionPassword.length > 256) { + throw new Error("Enter the disposable fixture username and session password"); + } + const packets = new Packets(stream); + try { + const nonce = greeting(await packets.read(0)); + const token = await authentication(sessionPassword, nonce); + sessionPassword = ""; + try { + await packets.write(concat(uint32(CLIENT_FLAGS), uint32(MAX_PACKET), Uint8Array.of(45), new Uint8Array(23), + zeroText(username), Uint8Array.of(token.length), token, zeroText("plugin_demo"), zeroText("mysql_native_password")), 1); + } finally { token.fill(0); nonce.fill(0); } + if ((await packets.read(2))[0] !== 0) reject(); + await packets.write(concat(Uint8Array.of(3), encoder.encode(READ_QUERY)), 0); + const count = await packets.read(1); + if (count.length !== 1 || count[0] !== 1) reject(); + const column = new Cursor(await packets.read(2)); + for (let index = 0; index < 4; index++) column.lengthText(); + if (column.lengthText() !== "value") reject(); + const eof = await packets.read(3); + if (eof[0] !== 0xfe || eof.length >= 9) reject(); + const row = new Cursor(await packets.read(4)); + const value = row.lengthText(); + if (row.offset !== row.bytes.length) reject(); + const end = await packets.read(5); + if (end[0] !== 0xfe || end.length >= 9) reject(); + return { columns: ["value"], rows: [[value]] }; + } finally { + sessionPassword = ""; + await stream.close(); + } +} diff --git a/global.d.ts b/global.d.ts index 49f74f65c..ba8293532 100644 --- a/global.d.ts +++ b/global.d.ts @@ -364,7 +364,15 @@ declare global { audit: Array<{ event: string; createdAt: number; permission?: string; scope?: string }>; } + interface NetcattyPluginSource { + id: string; + kind: 'official' | 'third-party' | 'local'; + name: string; + origin: string | null; + enabled?: boolean; + } interface NetcattyInstalledPlugin { + source?: NetcattyPluginSource; id: string; enabled: boolean; activeVersion: string | null; @@ -441,9 +449,15 @@ declare global { interface NetcattyBridge { getPluginRuntimeStatus?(): Promise; - listPluginCatalog?(): Promise; - getPluginCatalogReadme?(id: string, selectionToken?: string): Promise; - installCatalogPlugin?(id: string, selectionToken?: string): Promise; + getPluginSourceBinding?(pluginId: string): Promise; + resetPluginSource?(pluginId: string, expectedSourceId: string): Promise; + listPluginSources?(): Promise; + addPluginSource?(source: { name: string; address: string }): Promise; + updatePluginSource?(source: { id: string; name: string; enabled: boolean }): Promise; + removePluginSource?(id: string, disablePlugins: boolean): Promise; + listPluginCatalog?(sourceId?: string): Promise; + getPluginCatalogReadme?(id: string, selectionToken?: string, sourceId?: string): Promise; + installCatalogPlugin?(id: string, selectionToken?: string, sourceId?: string, acceptedSourceId?: string): Promise; setPluginInteractionReady?(ready: boolean): Promise; respondPluginInteraction?(response: import("@netcatty/plugin-contract").HostInteractionResponse): Promise; onPluginInteraction?(callback: (event: import("@netcatty/plugin-contract").HostInteractionEvent) => void): () => void; diff --git a/packages/plugin-cli/src/manifest.ts b/packages/plugin-cli/src/manifest.ts index d6dce01fc..0825dc2ea 100644 --- a/packages/plugin-cli/src/manifest.ts +++ b/packages/plugin-cli/src/manifest.ts @@ -369,6 +369,9 @@ function validateSemantics(manifest: PluginManifest): string[] { } const requiredFeatures = new Set(manifest.features?.required ?? []); + const hasByteStreams = [...(manifest.permissions?.required ?? []), ...(manifest.permissions?.optional ?? [])] + .some((declaration) => permissionName(declaration) === "network.stream"); + if (hasByteStreams && !requiredFeatures.has("network.byte-streams")) errors.push("Byte streams require network.byte-streams"); if ((manifest.main.data || manifest.contributes?.themes?.length) && !requiredFeatures.has('appearance.theme-packs')) errors.push('Theme packs require appearance.theme-packs'); for (const theme of manifest.contributes?.themes ?? []) if (!theme.entry.endsWith('.json')) errors.push('Theme palette entry must be JSON'); if (manifest.contributes?.views?.some((view) => view.location === 'terminal-sidebar') diff --git a/packages/plugin-contract/schema/plugin-contract.schema.json b/packages/plugin-contract/schema/plugin-contract.schema.json index 0b37e4f24..27db0013b 100644 --- a/packages/plugin-contract/schema/plugin-contract.schema.json +++ b/packages/plugin-contract/schema/plugin-contract.schema.json @@ -483,6 +483,439 @@ }, "additionalProperties": false }, + "PluginAIModelInvocationFeature": { + "const": "ai.model-invocation" + }, + "PluginSelectedContextFeature": { + "const": "context.selected-read" + }, + "PluginAIContextLimits": { + "const": { + "contexts": 4, + "inputBytes": 16384, + "chunkBytes": 4096, + "outputBytes": 32768, + "outputTokens": 2048, + "turnMs": 60000 + } + }, + "PluginAIEmptyParams": { + "type": "object", + "required": [], + "properties": {}, + "additionalProperties": false + }, + "PluginAIChatRef": { + "type": "object", + "required": [ + "chatHandle" + ], + "properties": { + "chatHandle": { + "type": "string", + "format": "uuid" + } + }, + "additionalProperties": false + }, + "PluginAITurnRef": { + "type": "object", + "required": [ + "turnHandle" + ], + "properties": { + "turnHandle": { + "type": "string", + "format": "uuid" + } + }, + "additionalProperties": false + }, + "PluginSelectedContextRef": { + "type": "object", + "required": [ + "handle", + "version" + ], + "properties": { + "handle": { + "type": "string", + "format": "uuid" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[^\\u0000]*$" + } + }, + "additionalProperties": false + }, + "PluginSelectedContextSummary": { + "type": "object", + "required": [ + "handle", + "scope", + "title", + "version", + "expiresAt" + ], + "properties": { + "handle": { + "type": "string", + "format": "uuid" + }, + "scope": { + "enum": [ + "workspace", + "tab", + "session", + "host", + "note" + ] + }, + "title": { + "type": "string", + "minLength": 0, + "maxLength": 160, + "pattern": "^[^\\u0000]*$" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[^\\u0000]*$" + }, + "expiresAt": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + "PluginSelectedContextContent": { + "type": "object", + "required": [ + "handle", + "scope", + "title", + "version", + "expiresAt", + "text" + ], + "properties": { + "handle": { + "type": "string", + "format": "uuid" + }, + "scope": { + "enum": [ + "workspace", + "tab", + "session", + "host", + "note" + ] + }, + "title": { + "type": "string", + "minLength": 0, + "maxLength": 160, + "pattern": "^[^\\u0000]*$" + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[^\\u0000]*$" + }, + "expiresAt": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "text": { + "type": "string", + "minLength": 0, + "maxLength": 16384, + "pattern": "^[^\\u0000]*$" + } + }, + "additionalProperties": false + }, + "PluginSelectedContextListResult": { + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "maxItems": 5, + "items": { + "$ref": "#/$defs/PluginSelectedContextSummary" + } + } + }, + "additionalProperties": false + }, + "PluginAIChatResult": { + "type": "object", + "required": [ + "chatHandle", + "model", + "expiresAt" + ], + "properties": { + "chatHandle": { + "type": "string", + "format": "uuid" + }, + "model": { + "type": "string", + "minLength": 0, + "maxLength": 160, + "pattern": "^[^\\u0000]*$" + }, + "expiresAt": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + "PluginAIStartTurnParams": { + "type": "object", + "required": [ + "chatHandle", + "prompt" + ], + "properties": { + "chatHandle": { + "type": "string", + "format": "uuid" + }, + "prompt": { + "type": "string", + "minLength": 1, + "maxLength": 16384, + "pattern": "^[^\\u0000]*$" + }, + "contexts": { + "type": "array", + "maxItems": 4, + "items": { + "$ref": "#/$defs/PluginSelectedContextRef" + } + } + }, + "additionalProperties": false + }, + "PluginAITurnResult": { + "type": "object", + "required": [ + "turnHandle", + "maxOutputTokens", + "reservedTokens" + ], + "properties": { + "turnHandle": { + "type": "string", + "format": "uuid" + }, + "maxOutputTokens": { + "const": 2048 + }, + "reservedTokens": { + "type": "integer", + "minimum": 1, + "maximum": 19456 + } + }, + "additionalProperties": false + }, + "PluginAIBooleanResult": { + "type": "object", + "required": [ + "ok" + ], + "properties": { + "ok": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "PluginAIStreamEvent": { + "oneOf": [ + { + "type": "object", + "required": [ + "kind", + "sequence", + "text" + ], + "properties": { + "kind": { + "const": "text" + }, + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 8192 + }, + "text": { + "type": "string", + "minLength": 0, + "maxLength": 4096, + "pattern": "^[^\\u0000]*$" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "required": [ + "kind", + "sequence" + ], + "properties": { + "kind": { + "const": "usage" + }, + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 8192 + }, + "inputTokens": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "totalTokens": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + { + "type": "object", + "required": [ + "kind", + "sequence" + ], + "properties": { + "kind": { + "const": "end" + }, + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 8192 + } + }, + "additionalProperties": false + } + ] + }, + "ByteStreamFeature": { + "const": "network.byte-streams" + }, + "ByteStreamLimits": { + "const": { + "connectionsPerRuntime": 4, + "connectionsTotal": 64, + "chunkBytes": 65536, + "bufferBytes": 65536, + "connectionBytes": 8388608, + "connectMs": 10000, + "idleMs": 30000, + "lifetimeMs": 120000 + } + }, + "ByteStreamEndpoint": { + "description": "An exact outgoing TCP or TLS endpoint. No userinfo, path, wildcard, query, or implicit port. The host further canonicalizes and checks DNS and control addresses.", + "type": "string", + "minLength": 9, + "maxLength": 512, + "pattern": "^(tcp|tls)://(\\[[0-9A-Fa-f:.]+\\]|[A-Za-z0-9.-]+):[1-9][0-9]{0,4}$" + }, + "ByteStreamConnectRequest": { + "type": "object", + "required": [ + "endpoint" + ], + "properties": { + "endpoint": { + "$ref": "#/$defs/ByteStreamEndpoint" + } + }, + "additionalProperties": false + }, + "ByteStreamHandleRequest": { + "type": "object", + "required": [ + "handleId" + ], + "properties": { + "handleId": { + "type": "string", + "format": "uuid" + } + }, + "additionalProperties": false + }, + "ByteStreamConnectionDescriptor": { + "type": "object", + "required": [ + "handleId", + "endpoint", + "inputStreamId", + "outputStreamId", + "windowBytes" + ], + "properties": { + "handleId": { + "type": "string", + "format": "uuid" + }, + "endpoint": { + "$ref": "#/$defs/ByteStreamEndpoint" + }, + "inputStreamId": { + "$ref": "#/$defs/StreamId" + }, + "outputStreamId": { + "$ref": "#/$defs/StreamId" + }, + "windowBytes": { + "const": 65536 + } + }, + "additionalProperties": false + }, + "ByteStreamAttachResult": { + "type": "object", + "required": [ + "attached" + ], + "properties": { + "attached": { + "const": true + } + }, + "additionalProperties": false + }, "NetworkCredentialLeaseFeature": { "const": "network.credential-lease" }, @@ -634,6 +1067,9 @@ "type": "string", "enum": [ "storage", + "ai.invoke", + "context.selected.list", + "context.selected.read", "runtime.advanced", "settings.read", "settings.write", @@ -656,6 +1092,7 @@ "sftp.read", "sftp.write", "network", + "network.stream", "filesystem.read", "filesystem.write", "secrets", @@ -672,6 +1109,9 @@ "type": "string", "enum": [ "storage", + "ai.invoke", + "context.selected.list", + "context.selected.read", "runtime.advanced", "settings.read", "settings.write", @@ -706,6 +1146,7 @@ "type": "string", "enum": [ "network", + "network.stream", "filesystem.read", "filesystem.write", "companion.execute" @@ -743,11 +1184,13 @@ }, "reason": { "type": "string", "maxLength": 1024 } }, + "if": { "properties": { "permission": { "const": "network.stream" } } }, + "then": { "properties": { "resources": { "type": "array", "items": { "$ref": "#/$defs/ByteStreamEndpoint" } } } }, "additionalProperties": false }, "PermissionDeclaration": { "oneOf": [ - { "$ref": "#/$defs/PluginPermission" }, + { "$ref": "#/$defs/PluginPermission", "not": { "const": "network.stream" } }, { "$ref": "#/$defs/PermissionResourceDeclaration" } ] }, @@ -765,6 +1208,8 @@ }, "reason": { "type": "string", "maxLength": 1024 } }, + "if": { "properties": { "permission": { "const": "network.stream" } } }, + "then": { "properties": { "resources": { "type": "array", "items": { "$ref": "#/$defs/ByteStreamEndpoint" } } } }, "additionalProperties": false }, "RequiredPermissionDeclaration": { diff --git a/packages/plugin-contract/src/generated/plugin-contract-limits.ts b/packages/plugin-contract/src/generated/plugin-contract-limits.ts index f667ba03b..8df8a1fc6 100644 --- a/packages/plugin-contract/src/generated/plugin-contract-limits.ts +++ b/packages/plugin-contract/src/generated/plugin-contract-limits.ts @@ -7,6 +7,7 @@ export const PLUGIN_JSON_MAX_NODES = 100000 as const; export const PLUGIN_WIRE_MAX_SAFE_INTEGER = 9007199254740991 as const; export const PLUGIN_RPC_MAX_JSON_BYTES = 1048576 as const; export const PLUGIN_HOST_INTERACTION_LIMITS = {"textBytes":4096,"requestBytes":65536,"items":100,"pendingPerRuntime":1,"pendingTotal":8,"requestsPerMinute":10,"timeoutMs":60000} as const; +export const PLUGIN_BYTE_STREAM_LIMITS = {"connectionsPerRuntime":4,"connectionsTotal":64,"chunkBytes":65536,"bufferBytes":65536,"connectionBytes":8388608,"connectMs":10000,"idleMs":30000,"lifetimeMs":120000} as const; export const PLUGIN_RPC_ERROR_CODES = [-32700,-32600,-32601,-32602,-32603,-32001,-32002,-32003,-32004,-32005,-32006,-32007,-32008,-32009,-32010,-32011,-32012,-32013,-32014,-32015,-32016] as const; export const PLUGIN_STREAM_MAX_ID_LENGTH = 128 as const; export const PLUGIN_STREAM_MAX_CHUNK_BYTES = 16777216 as const; diff --git a/packages/plugin-contract/src/generated/plugin-contract.ts b/packages/plugin-contract/src/generated/plugin-contract.ts index 032267102..dfe20651b 100644 --- a/packages/plugin-contract/src/generated/plugin-contract.ts +++ b/packages/plugin-contract/src/generated/plugin-contract.ts @@ -73,6 +73,32 @@ export type AuthenticationResult = ({ export type BoundedPermissionResource = string; +export type ByteStreamAttachResult = { + attached: true; +}; + +export type ByteStreamConnectionDescriptor = { + handleId: string; + endpoint: ByteStreamEndpoint; + inputStreamId: StreamId; + outputStreamId: StreamId; + windowBytes: 65536; +}; + +export type ByteStreamConnectRequest = { + endpoint: ByteStreamEndpoint; +}; + +export type ByteStreamEndpoint = string; + +export type ByteStreamFeature = "network.byte-streams"; + +export type ByteStreamHandleRequest = { + handleId: string; +}; + +export type ByteStreamLimits = {"connectionsPerRuntime":4,"connectionsTotal":64,"chunkBytes":65536,"bufferBytes":65536,"connectionBytes":8388608,"connectMs":10000,"idleMs":30000,"lifetimeMs":120000}; + export type CommandContribution = { id: ContributionId; title: LocalizedText; @@ -431,7 +457,7 @@ export type MenuLocation = "commandPalette" | "application" | "host/context" | " export type NetworkCredentialLeaseFeature = "network.credential-lease"; -export type NonResourceScopedPermission = "storage" | "runtime.advanced" | "settings.read" | "settings.write" | "commands" | "menus" | "views" | "ui.interact" | "clipboard.read" | "clipboard.write" | "terminal.metadata" | "terminal.output" | "terminal.input" | "terminal.decorate" | "terminal.complete" | "terminal.intercept.input" | "terminal.intercept.output" | "vault.metadata" | "vault.write" | "vault.credentials" | "sftp.read" | "sftp.write" | "secrets" | "provider.terminal" | "provider.connection" | "provider.authentication" | "provider.sync" | "provider.importer"; +export type NonResourceScopedPermission = "storage" | "ai.invoke" | "context.selected.list" | "context.selected.read" | "runtime.advanced" | "settings.read" | "settings.write" | "commands" | "menus" | "views" | "ui.interact" | "clipboard.read" | "clipboard.write" | "terminal.metadata" | "terminal.output" | "terminal.input" | "terminal.decorate" | "terminal.complete" | "terminal.intercept.input" | "terminal.intercept.output" | "vault.metadata" | "vault.write" | "vault.credentials" | "sftp.read" | "sftp.write" | "secrets" | "provider.terminal" | "provider.connection" | "provider.authentication" | "provider.sync" | "provider.importer"; export type NullableRpcId = (RpcId) | (null); @@ -451,7 +477,7 @@ export type PermissionDecision = ({ decision: "deny" | "cancel"; }); -export type PermissionDeclaration = (PluginPermission) | (PermissionResourceDeclaration); +export type PermissionDeclaration = Exclude | PermissionResourceDeclaration; export type PermissionGrantScope = "once" | "session" | "application" | "always"; @@ -487,6 +513,57 @@ export type PermissionSet = { optional?: Array; }; +export type PluginAIBooleanResult = { + ok: boolean; +}; + +export type PluginAIChatRef = { + chatHandle: string; +}; + +export type PluginAIChatResult = { + chatHandle: string; + model: string; + expiresAt: number; +}; + +export type PluginAIContextLimits = {"contexts":4,"inputBytes":16384,"chunkBytes":4096,"outputBytes":32768,"outputTokens":2048,"turnMs":60000}; + +export type PluginAIEmptyParams = Record; + +export type PluginAIModelInvocationFeature = "ai.model-invocation"; + +export type PluginAIStartTurnParams = { + chatHandle: string; + prompt: string; + contexts?: Array; +}; + +export type PluginAIStreamEvent = ({ + kind: "text"; + sequence: number; + text: string; +}) | ({ + kind: "usage"; + sequence: number; + inputTokens?: number; + outputTokens?: number; + totalTokens?: number; +}) | ({ + kind: "end"; + sequence: number; +}); + +export type PluginAITurnRef = { + turnHandle: string; +}; + +export type PluginAITurnResult = { + turnHandle: string; + maxOutputTokens: 2048; + reservedTokens: number; +}; + export type PluginContributions = { themes?: Array; settings?: Array; @@ -587,7 +664,35 @@ export type PluginNetworkResponse = { }; }; -export type PluginPermission = "storage" | "runtime.advanced" | "settings.read" | "settings.write" | "commands" | "menus" | "views" | "ui.interact" | "clipboard.read" | "clipboard.write" | "terminal.metadata" | "terminal.output" | "terminal.input" | "terminal.decorate" | "terminal.complete" | "terminal.intercept.input" | "terminal.intercept.output" | "vault.metadata" | "vault.write" | "vault.credentials" | "sftp.read" | "sftp.write" | "network" | "filesystem.read" | "filesystem.write" | "secrets" | "companion.execute" | "provider.terminal" | "provider.connection" | "provider.authentication" | "provider.sync" | "provider.importer"; +export type PluginPermission = "storage" | "ai.invoke" | "context.selected.list" | "context.selected.read" | "runtime.advanced" | "settings.read" | "settings.write" | "commands" | "menus" | "views" | "ui.interact" | "clipboard.read" | "clipboard.write" | "terminal.metadata" | "terminal.output" | "terminal.input" | "terminal.decorate" | "terminal.complete" | "terminal.intercept.input" | "terminal.intercept.output" | "vault.metadata" | "vault.write" | "vault.credentials" | "sftp.read" | "sftp.write" | "network" | "network.stream" | "filesystem.read" | "filesystem.write" | "secrets" | "companion.execute" | "provider.terminal" | "provider.connection" | "provider.authentication" | "provider.sync" | "provider.importer"; + +export type PluginSelectedContextContent = { + handle: string; + scope: "workspace" | "tab" | "session" | "host" | "note"; + title: string; + version: string; + expiresAt: number; + text: string; +}; + +export type PluginSelectedContextFeature = "context.selected-read"; + +export type PluginSelectedContextListResult = { + items: Array; +}; + +export type PluginSelectedContextRef = { + handle: string; + version: string; +}; + +export type PluginSelectedContextSummary = { + handle: string; + scope: "workspace" | "tab" | "session" | "host" | "note"; + title: string; + version: string; + expiresAt: number; +}; export type PluginViewFocusEvent = { instanceId: string; @@ -670,7 +775,7 @@ export type RequiredPermissionResourceDeclaration = { reason?: string; }; -export type ResourceScopedPermission = "network" | "filesystem.read" | "filesystem.write" | "companion.execute"; +export type ResourceScopedPermission = "network" | "network.stream" | "filesystem.read" | "filesystem.write" | "companion.execute"; export type RpcCancel = { jsonrpc: "2.0"; diff --git a/packages/plugin-contract/src/index.ts b/packages/plugin-contract/src/index.ts index 4afd81bef..9e9a4c1fc 100644 --- a/packages/plugin-contract/src/index.ts +++ b/packages/plugin-contract/src/index.ts @@ -11,6 +11,7 @@ export { } from "./jsonValue.js"; export { PLUGIN_HOST_INTERACTION_LIMITS, + PLUGIN_BYTE_STREAM_LIMITS, PLUGIN_IMPORTER_MAX_INPUT_BYTES, PLUGIN_IMPORTER_MAX_OUTPUT_BYTES, PLUGIN_IMPORTER_MAX_RECORD_BYTES, @@ -52,6 +53,9 @@ export { export { inspectPluginBrandIcon, PLUGIN_BRAND_ICON_FEATURE, PLUGIN_BRAND_ICON_MAX_BYTES, PLUGIN_BRAND_ICON_MAX_EDGE } from './brandIcon.js'; export const PLUGIN_NETWORK_CREDENTIAL_LEASE_FEATURE = "network.credential-lease" as const satisfies import("./generated/plugin-contract.js").NetworkCredentialLeaseFeature; +export const PLUGIN_BYTE_STREAM_FEATURE = "network.byte-streams" as const satisfies import("./generated/plugin-contract.js").ByteStreamFeature; +export const PLUGIN_AI_MODEL_INVOCATION_FEATURE = "ai.model-invocation" as const satisfies import("./generated/plugin-contract.js").PluginAIModelInvocationFeature; +export const PLUGIN_SELECTED_CONTEXT_FEATURE = "context.selected-read" as const satisfies import("./generated/plugin-contract.js").PluginSelectedContextFeature; export const PLUGIN_HOST_INTERACTION_FEATURE = "host.interactions" as const satisfies import("./generated/plugin-contract.js").HostInteractionFeature; diff --git a/packages/plugin-sdk/src/index.ts b/packages/plugin-sdk/src/index.ts index 4aa74cc80..51816c5cb 100644 --- a/packages/plugin-sdk/src/index.ts +++ b/packages/plugin-sdk/src/index.ts @@ -655,6 +655,28 @@ export type { PluginNetworkAuthorization, PluginNetworkRequest, PluginNetworkRes export interface PluginNetworkClient { request(request: PluginNetworkRequest): Promise; + connect(request: import("@netcatty/plugin-contract").ByteStreamConnectRequest, cancellationToken?: CancellationToken): Promise; +} + +export interface PluginAIClient { + openChat(params: import("@netcatty/plugin-contract").PluginAIEmptyParams): Promise; + startTurn(params: import("@netcatty/plugin-contract").PluginAIStartTurnParams): Promise; + readTurn(params: import("@netcatty/plugin-contract").PluginAITurnRef): Promise; + stopTurn(params: import("@netcatty/plugin-contract").PluginAITurnRef): Promise; + closeChat(params: import("@netcatty/plugin-contract").PluginAIChatRef): Promise; +} + +export interface PluginSelectedContextClient { + list(params: import("@netcatty/plugin-contract").PluginAIEmptyParams): Promise; + read(params: import("@netcatty/plugin-contract").PluginSelectedContextRef): Promise; +} + +export interface PluginByteConnection extends Disposable { + readonly endpoint: string; + readonly readable: PluginReadableByteStream; + readonly writable: PluginWritableByteStream; + /** Closes both directions. Repeated calls on this handle are harmless. */ + close(): Promise; } export interface PluginFilesystemEntry { @@ -746,6 +768,8 @@ export interface PluginContext { readonly secrets: PluginSecretStore; readonly credentials: PluginCredentialBroker; readonly network: PluginNetworkClient; + readonly ai: PluginAIClient; + readonly selectedContext: PluginSelectedContextClient; readonly filesystem: PluginFilesystemClient; readonly companions: PluginCompanionService; readonly streams: PluginStreams; @@ -928,6 +952,8 @@ export function throwIfCancellationRequested(token: CancellationToken): void { } export { PLUGIN_NETWORK_CREDENTIAL_LEASE_FEATURE } from "@netcatty/plugin-contract"; +export { PLUGIN_BYTE_STREAM_FEATURE, PLUGIN_BYTE_STREAM_LIMITS } from "@netcatty/plugin-contract"; +export { PLUGIN_AI_MODEL_INVOCATION_FEATURE, PLUGIN_SELECTED_CONTEXT_FEATURE } from "@netcatty/plugin-contract"; export { PLUGIN_HOST_INTERACTION_FEATURE } from "@netcatty/plugin-contract"; export { PLUGIN_VAULT_PAGES_FEATURE } from "@netcatty/plugin-contract"; diff --git a/scripts/generate-plugin-contract.mjs b/scripts/generate-plugin-contract.mjs index ffc47625d..2f8922ce5 100644 --- a/scripts/generate-plugin-contract.mjs +++ b/scripts/generate-plugin-contract.mjs @@ -22,6 +22,7 @@ const electronBundlePath = path.join( ); const checkOnly = process.argv.includes("--check"); const typescriptTypeOverrides = new Map([ + ["PermissionDeclaration", 'Exclude | PermissionResourceDeclaration'], [ "ActivationEvent", '"onStartupFinished" | `onCommand:${ContributionId}` | `onView:${ContributionId}` | `onProvider:${ContributionId}`', @@ -306,6 +307,10 @@ function schemaTypeToTs(node, level = 0) { } const hostInteractionLimits = schema.$defs.HostInteractionLimits?.const; +const byteStreamLimits = schema.$defs.ByteStreamLimits?.const; +if (!byteStreamLimits || Object.values(byteStreamLimits).some((value) => !Number.isSafeInteger(value) || value < 1)) { + throw new Error("ByteStreamLimits must contain positive bounded integers"); +} if (!hostInteractionLimits || Object.values(hostInteractionLimits).some((value) => !Number.isSafeInteger(value) || value < 1)) { throw new Error("HostInteractionLimits must contain positive bounded integers"); } @@ -333,6 +338,7 @@ const generatedLimits = [ `export const PLUGIN_WIRE_MAX_SAFE_INTEGER = ${wireIntegerLimits.maxSafeInteger} as const;`, `export const PLUGIN_RPC_MAX_JSON_BYTES = ${rpcLimits.maxJsonBytes} as const;`, `export const PLUGIN_HOST_INTERACTION_LIMITS = ${JSON.stringify(hostInteractionLimits)} as const;`, + `export const PLUGIN_BYTE_STREAM_LIMITS = ${JSON.stringify(byteStreamLimits)} as const;`, `export const PLUGIN_RPC_ERROR_CODES = ${JSON.stringify(rpcErrorCodes)} as const;`, `export const PLUGIN_STREAM_MAX_ID_LENGTH = ${streamLimits.maxStreamIdLength} as const;`, `export const PLUGIN_STREAM_MAX_CHUNK_BYTES = ${streamLimits.maxChunkBytes} as const;`,