diff --git a/docs/plugin-platform/terminal-sharing-wip.md b/docs/plugin-platform/terminal-sharing-wip.md new file mode 100644 index 000000000..a4ceb6da2 --- /dev/null +++ b/docs/plugin-platform/terminal-sharing-wip.md @@ -0,0 +1,51 @@ +# Selected terminal sharing — implementation WIP + +Base: ThemePack `f868221b5f11810802f929369ac8eee46166079a`. +Branch: `feat/plugin-terminal-sharing`. This is saved unfinished source, not an +accepted API or an installable/native-tested workflow. Do not merge or release. + +Implemented source so far: + +- Canonical optional action-only `terminal.selection.read`, feature + `terminal.selection-sharing`, bounded result and host-target schemas; SDK + `context.terminals.shareSelection()` and runtime forwarding through the + existing `ui.interact` broker. No independent parallel RPC stack. +- Main-only worker/session generation and window-owner binding accessor; no + endpoint or Host DTO returned to plugins. +- Host target/handle authority, opaque signed short-lived receipts, capacity, + expiry and lifecycle hooks; no selected text stored in the authority. +- Broker admission binding to the selected resource before a once-only grant, + signed Preview/Share phases, fixed audit metadata and teardown integration. +- Trusted app-only selected-target setter, not a plugin API. No database, + installation/source/cache identity or private-storage schema changes. + +Still missing, and required before this counts as working: + +1. Trusted renderer target publication for the real active terminal/workspace; + actual bounded selection reader registered by the terminal surface. Read + only on Preview, from a visible connected terminal, never through Agent/MCP + history/context readers; refuse sensitive input, empty or oversized selection. +2. Host dialog Preview response and explicit Share rendering, failure states, + exact resource/selection consistency and global lifecycle verification. +3. Canonical/SDK/broker/authority/real-worker/renderer normal and boundary tests, + generated-contract and compatibility review (including optional-only + declaration semantics), quotas, owner/reconnect/close/revoke/late-result cases. +4. Useful ordinary-browser synthetic example, fixture ID/hash/precise permissions, + build/CI, independent review/fix/review and parent-owned native acceptance. +5. Separate input-draft layer: reuse the actual compose control without inheriting + broadcast targets, overwriting an existing draft silently, writing PTY bytes + or sending Enter. Require a separately approved target-bound draft action and + final active identity check. No input-proposal method/permission is delivered + by this WIP. + +Known integration constraints: + +- The market source-binding task owns installation, cache, authorization/private + storage identity and associated database schema. Coordinate before touching + those locations; runtime/assertActive identity must remain host-owned. +- Keep the ThemePack security-color delta in its own branch/head. Incorporate + the eventually accepted head with a normal integration merge, not by rewriting + frozen evidence. +- The user allows simplification of unreleased plugin historical data/protocols; + do not add legacy migration layers. Do not remove unrelated host/input data + migrations or weaken the sandbox. diff --git a/domain/pluginPermissionDescriptions.cjs b/domain/pluginPermissionDescriptions.cjs index 3e74a3825..64ee37b43 100644 --- a/domain/pluginPermissionDescriptions.cjs +++ b/domain/pluginPermissionDescriptions.cjs @@ -13,6 +13,7 @@ const PERMISSION_DESCRIPTIONS = { views: [false, "Plugin panels", "Display plugin-owned panels inside the app.", "插件面板", "在应用中显示插件自己的面板。"], "clipboard.read": [true, "Read clipboard", "Read copied text, which may contain passwords or other sensitive data.", "读取剪贴板", "读取复制的文本,其中可能包含密码或其他敏感数据。"], "clipboard.write": [true, "Write clipboard", "Replace clipboard content that you may paste elsewhere.", "写入剪贴板", "替换剪贴板内容,可能影响你随后粘贴的数据。"], + "terminal.selection.read": [true, "Share terminal selection", "Read only text explicitly previewed and shared from the selected live terminal. It may contain secrets. Each action requires approval.", "分享终端选区", "仅读取用户从当前活跃终端明确预览并分享的文本,可能包含秘密;每次操作均需确认。"], "terminal.metadata": [true, "Terminal metadata", "Read terminal/session details that may identify hosts and activity.", "终端元数据", "读取终端和会话信息,可能暴露主机及操作活动。"], "terminal.output": [true, "Read terminal output", "Receive terminal output through supported providers; it may contain credentials or private data.", "读取终端输出", "通过支持的提供器接收终端输出,其中可能包含凭据或隐私信息。"], "terminal.input": [true, "Send terminal input", "Send input to a terminal; input may execute commands or change a remote host.", "发送终端输入", "向终端发送输入,可能执行命令或更改远程主机。"], diff --git a/electron/bridges/terminalWorkerManager.cjs b/electron/bridges/terminalWorkerManager.cjs index dd1403a6d..d3f68d72e 100644 --- a/electron/bridges/terminalWorkerManager.cjs +++ b/electron/bridges/terminalWorkerManager.cjs @@ -390,6 +390,7 @@ function createTerminalWorkerManager(options = {}) { onRendererEvent = null, } = options; let child = null; + let pluginSessionAuthorityEpoch = 0; const pending = new Map(); const pendingOutput = new Map(); const pendingOutputBytes = new Map(); @@ -1857,6 +1858,7 @@ function createTerminalWorkerManager(options = {}) { }, }); child = worker; + pluginSessionAuthorityEpoch++; worker.on?.("message", (message) => { if (child === worker) handleMessage(message); }); @@ -2246,6 +2248,14 @@ function createTerminalWorkerManager(options = {}) { if (!sessionId) return null; return sessionWebContentsIds.get(sessionId) ?? null; }, + // Main-process resource authority only; never expose worker objects or endpoints. + getPluginSessionBinding(sessionId, webContentsId) { + const generation = sessionGenerations.get(sessionId); + if (!child || !Number.isSafeInteger(generation) || closedSessions.has(sessionId) + || pendingSessionStartSequences.has(sessionId) || outputRoutePending.has(sessionId) + || sessionWebContentsIds.get(sessionId) !== webContentsId || !isLiveWebContentsId(webContentsId)) return null; + return Object.freeze({ epoch: pluginSessionAuthorityEpoch, generation }); + }, getSessionHostId(sessionId) { if (!sessionId) return null; return sessionHostIds.get(sessionId) ?? null; diff --git a/electron/main/registerBridges.cjs b/electron/main/registerBridges.cjs index 21452b74d..df68e9821 100644 --- a/electron/main/registerBridges.cjs +++ b/electron/main/registerBridges.cjs @@ -166,6 +166,7 @@ function createBridgeRegistrar(context) { electron: electronModule, safeStorage, getInteractionWindow: () => win, + getTerminalWorkerManager: () => terminalWorkerManager, isAppLocked: () => getAppLockController?.()?.getRuntimeState?.()?.locked !== false, subscribeAppLock: (listener) => getAppLockController?.()?.subscribe?.(listener), requestPermissionDecision: createNativePermissionDecisionProvider({ diff --git a/electron/plugins/generated/plugin-contract.schema.json b/electron/plugins/generated/plugin-contract.schema.json index ebcc2a6a9..ed9109c67 100644 --- a/electron/plugins/generated/plugin-contract.schema.json +++ b/electron/plugins/generated/plugin-contract.schema.json @@ -390,6 +390,9 @@ }, { "$ref": "#/$defs/HostClipboardWriteRequest" + }, + { + "$ref": "#/$defs/HostTerminalSelectionReadRequest" } ] }, @@ -426,6 +429,9 @@ }, { "const": true + }, + { + "$ref": "#/$defs/SharedTerminalSelection" } ] } @@ -536,6 +542,11 @@ "type": "string", "maxLength": 4096, "pattern": "^[^\\u0000]*$" + }, + "terminalSessionId": { + "type": "string", + "maxLength": 128, + "pattern": "^[A-Za-z0-9_-]+$" } }, "additionalProperties": false @@ -731,7 +742,8 @@ "provider.connection", "provider.authentication", "provider.sync", - "provider.importer" + "provider.importer", + "terminal.selection.read" ] }, "NonResourceScopedPermission": { @@ -765,7 +777,8 @@ "provider.connection", "provider.authentication", "provider.sync", - "provider.importer" + "provider.importer", + "terminal.selection.read" ] }, "ResourceScopedPermission": { @@ -872,7 +885,10 @@ { "$ref": "#/$defs/RequiredPermissionResourceDeclaration" } - ] + ], + "not": { + "const": "terminal.selection.read" + } }, "PermissionSet": { "type": "object", @@ -5163,6 +5179,77 @@ "entries", "diagnostics" ] + }, + "TerminalSelectionSharingFeature": { + "const": "terminal.selection-sharing" + }, + "TerminalSelectionSharingLimits": { + "const": { + "textBytes": 4096, + "handleTtlMs": 120000, + "handlesPerRuntime": 4, + "handlesTotal": 64 + } + }, + "HostTerminalTarget": { + "type": "object", + "properties": { + "sessionId": { + "type": [ + "string", + "null" + ], + "maxLength": 128, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "HostTerminalSelectionReadRequest": { + "type": "object", + "properties": { + "kind": { + "const": "terminal.selection.read" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 256 + } + }, + "required": [ + "kind", + "title" + ], + "additionalProperties": false + }, + "SharedTerminalSelection": { + "type": "object", + "properties": { + "text": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^[^\\u0000]*$" + }, + "handle": { + "type": "string", + "minLength": 64, + "maxLength": 256 + }, + "expiresAt": { + "$ref": "#/$defs/SafePositiveInteger" + } + }, + "required": [ + "text", + "handle", + "expiresAt" + ], + "additionalProperties": false } } } diff --git a/electron/plugins/hostInteractionService.cjs b/electron/plugins/hostInteractionService.cjs index 2d4c36dbb..ef9a9359b 100644 --- a/electron/plugins/hostInteractionService.cjs +++ b/electron/plugins/hostInteractionService.cjs @@ -2,6 +2,7 @@ const { createHmac, randomBytes, randomUUID, timingSafeEqual } = require("node:crypto"); const { createDefinitionValidator } = require("./contractValidator.cjs"); +const { TerminalSelectionAuthority } = require("./terminalSelectionAuthority.cjs"); const { PluginRpcError, RPC_ERRORS } = require("./rpcRouter.cjs"); const schema = require("./generated/plugin-contract.schema.json"); const LIMITS = schema.$defs.HostInteractionLimits.const; @@ -31,7 +32,12 @@ function assertInteractionRequest(params) { } return Object.freeze(structuredClone(params)); } -function interactionAuthorization(params) { +function interactionAuthorization(params, terminalTarget) { + if (params.kind === "terminal.selection.read") { + if (!terminalTarget) throw fail("failedPrecondition", "A host-selected terminal is required"); + return { permission: "terminal.selection.read", resources: [terminalTarget.resource], + reason: "Preview and explicitly share the selected terminal text", operationId: "terminal:share-selection", allowedScopes: ["once"] }; + } const permission = params.kind === "clipboard.read" ? "clipboard.read" : params.kind === "clipboard.write" ? "clipboard.write" : "ui.interact"; return { @@ -55,6 +61,12 @@ class PluginHostInteractionService { this.timeoutMs = Math.min(options.timeoutMs ?? LIMITS.timeoutMs, LIMITS.timeoutMs); this.key = randomBytes(32); this.pending = new Map(); + this.terminalSelection = new TerminalSelectionAuthority({getWindow: this.getWindow, getManager: options.getTerminalWorkerManager, clock: this.clock}); + this.terminalInvalidation = this.terminalSelection.onDidInvalidate(() => { + for (const entry of [...this.pending.values()]) if (entry.terminalTarget && !this.terminalSelection.isCurrent(entry.terminalTarget)) { + this.#finish(entry, null, fail("cancelled", "Selected terminal connection changed")); + } + }); this.rates = new Map(); this.admissions = new WeakMap(); this.admissionGuards = new Map(); @@ -75,8 +87,9 @@ class PluginHostInteractionService { const sender = this.#admit(params, context); let guard = this.admissionGuards.get(context.runtimeId); if (!guard) { guard = { active: true }; this.admissionGuards.set(context.runtimeId, guard); } - this.admissions.set(params, { sender, runtimeId: context.runtimeId, revision: this.admissionRevision, guard }); - return interactionAuthorization(params); + const terminalTarget = params.kind === "terminal.selection.read" ? this.terminalSelection.capture(sender, context) : undefined; + this.admissions.set(params, { sender, runtimeId: context.runtimeId, revision: this.admissionRevision, guard, terminalTarget }); + return interactionAuthorization(params, terminalTarget); }, }); } @@ -132,7 +145,7 @@ class PluginHostInteractionService { const nonce = randomBytes(24).toString("base64url"); const binding = JSON.stringify([ nonce, entry.id, entry.context.pluginId, entry.context.pluginVersion, - entry.context.runtimeId, entry.sender.id, entry.params.kind, entry.phase, entry.expiresAt, + entry.context.runtimeId, entry.sender.id, entry.params.kind, entry.phase, entry.expiresAt, entry.terminalTarget?.resource ?? null, ]); return `${nonce}.${createHmac("sha256", this.key).update(binding).digest("base64url")}`; } @@ -143,6 +156,7 @@ class PluginHostInteractionService { requestId: entry.id, actionToken: entry.actionToken, pluginId: entry.context.pluginId, pluginVersion: entry.context.pluginVersion, expiresAt: entry.expiresAt, phase: entry.phase, request: entry.params, + ...(entry.terminalTarget ? { terminalSessionId: entry.terminalTarget.sessionId } : {}), ...(entry.previewText === undefined ? {} : { previewText: entry.previewText }), }); } @@ -222,10 +236,13 @@ class PluginHostInteractionService { if (this.pending.size >= LIMITS.pendingTotal || [...this.pending.values()].some((entry) => entry.context.runtimeId === context.runtimeId || entry.sender === sender)) { throw fail("resourceExhausted", "Host interaction limit reached"); } + const terminalTarget = params.kind === "terminal.selection.read" + ? admission?.terminalTarget ?? this.terminalSelection.capture(sender, context) : undefined; + if (terminalTarget) this.terminalSelection.assertCurrent(terminalTarget); const now = this.clock(); return new Promise((resolve, reject) => { const entry = { - id: randomUUID(), context, params, sender, resolve, reject, + id: randomUUID(), context, params, sender, resolve, reject, terminalTarget, expiresAt: now + this.timeoutMs, phase: "request", actionToken: null, }; entry.onAbort = () => this.#finish(entry, null, fail("cancelled", "Host interaction was cancelled")); @@ -254,10 +271,19 @@ class PluginHostInteractionService { await entry.context.assertActive(); this.#assertWindow(sender); if (this.pending.get(entry.id) !== entry) return false; + if (entry.terminalTarget) this.terminalSelection.assertCurrent(entry.terminalTarget); if (response.action === "cancel") { this.#audit(entry, "cancelled"); return this.#finish(entry, { cancelled: true }); } + if (entry.params.kind === "terminal.selection.read" && entry.phase === "request") { + if (response.action !== "preview") throw fail("invalidArgument", "Terminal sharing requires a preview action"); + const text = assertTextBytes(response.value); + if (!text.length) throw fail("failedPrecondition", "Select terminal text before requesting a share"); + this.#audit(entry, "preview-confirmed"); + this.quotaManager.chargeBytes(entry.context.runtimeId, "terminal", Buffer.byteLength(text)); + entry.previewText = text; entry.phase = "preview"; this.#present(entry); return true; + } if (entry.params.kind === "clipboard.read" && entry.phase === "request") { if (response.action !== "preview") throw fail("invalidArgument", "Clipboard sharing requires a preview action"); this.#audit(entry, "preview-confirmed"); @@ -281,6 +307,9 @@ class PluginHostInteractionService { else if (entry.params.kind === "quickPick") { if (!entry.params.items.some((item) => item.id === response.value)) throw fail("invalidArgument", "Host interaction choice is invalid"); value = response.value; + } else if (entry.params.kind === "terminal.selection.read") { + if (entry.phase !== "preview" || typeof entry.previewText !== "string") throw fail("failedPrecondition", "Terminal selection was not previewed"); + value = {text:entry.previewText, ...this.terminalSelection.issue(entry.terminalTarget, entry.context)}; } else if (entry.params.kind === "clipboard.read") value = entry.previewText; else value = true; this.#audit(entry, entry.params.kind === "clipboard.write" ? "copy-confirmed" : "share-confirmed"); @@ -295,8 +324,11 @@ class PluginHostInteractionService { } } + setTerminalTarget(sender, target) { return this.terminalSelection.setTarget(sender, target); } + releaseWindow(sender) { if (this.owner !== sender) return; + this.terminalSelection.releaseWindow(sender); this.admissionRevision++; this.owner = null; this.ownerCleanup?.(); this.ownerCleanup = null; @@ -305,12 +337,14 @@ class PluginHostInteractionService { } } releasePlugin(pluginId) { + this.terminalSelection.releasePlugin(pluginId); this.admissionRevision++; for (const entry of [...this.pending.values()]) { if (entry.context.pluginId === pluginId) this.#finish(entry, null, fail("cancelled", "Plugin access was revoked")); } } releaseRuntime(runtimeId) { + this.terminalSelection.releaseRuntime(runtimeId); this.cancelRuntimeRequests(runtimeId, "Plugin runtime stopped"); this.rates.delete(runtimeId); } @@ -323,7 +357,7 @@ class PluginHostInteractionService { } } cancelAll(invalidateAdmission = true) { - if (invalidateAdmission) this.admissionRevision++; + if (invalidateAdmission) { this.admissionRevision++; this.terminalSelection.clearHandles(); } for (const entry of [...this.pending.values()]) this.#finish(entry, null, fail("cancelled", "Host interaction was cancelled")); } shutdown() { @@ -332,6 +366,7 @@ class PluginHostInteractionService { if (this.owner) this.releaseWindow(this.owner); this.cancelAll(); this.rates.clear(); this.admissionGuards.clear(); this.revocation.dispose(); this.unsubscribeLock?.(); + this.terminalInvalidation.dispose(); this.terminalSelection.shutdown(); this.key.fill(0); } } diff --git a/electron/plugins/hostService.cjs b/electron/plugins/hostService.cjs index 8b2208ebc..9037be213 100644 --- a/electron/plugins/hostService.cjs +++ b/electron/plugins/hostService.cjs @@ -99,7 +99,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: [...new Set(["terminal.selection-sharing", "appearance.theme-packs", "metadata.brand-icon", NETWORK_CREDENTIAL_LEASE_FEATURE, HOST_INTERACTION_FEATURE, VAULT_PAGES_FEATURE, TERMINAL_SIDEBAR_FEATURE, INTERACTIVE_COMMAND_FEATURE, ...(options.supportedFeatures ?? [])])], }); const contributionIconService = new PluginContributionIconService({ database, @@ -190,6 +190,7 @@ function createPluginHostService(options) { getWindow: options.getInteractionWindow, isLocked: options.isAppLocked, subscribeLock: options.subscribeAppLock, + getTerminalWorkerManager: options.getTerminalWorkerManager, }); interactionService.registerRpcCapabilities(rpcRegistry); const configuredRegistry = options.configureRpcRegistry?.(rpcRegistry); @@ -239,7 +240,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: [...new Set(["terminal.selection-sharing", "appearance.theme-packs", "metadata.brand-icon", NETWORK_CREDENTIAL_LEASE_FEATURE, HOST_INTERACTION_FEATURE, VAULT_PAGES_FEATURE, TERMINAL_SIDEBAR_FEATURE, INTERACTIVE_COMMAND_FEATURE, ...(options.supportedFeatures ?? [])])], runtimeDirectory, appRoot, rpcRegistry, diff --git a/electron/plugins/pluginBridge.cjs b/electron/plugins/pluginBridge.cjs index a5123674a..7c7c68e2e 100644 --- a/electron/plugins/pluginBridge.cjs +++ b/electron/plugins/pluginBridge.cjs @@ -20,6 +20,7 @@ const CHANNELS = Object.freeze({ themeApply: "netcatty:plugins:theme-apply", themesChanged: "netcatty:plugins:themes-changed", status: "netcatty:plugins:status", + terminalTarget: "netcatty:plugins:terminal-target", interactionReady: "netcatty:plugins:interaction-ready", interactionResponse: "netcatty:plugins:interaction-response", list: "netcatty:plugins:list", @@ -726,6 +727,10 @@ function registerPluginBridge(ipcMain, options) { )); handle(CHANNELS.restart, async (activeManager, payload) => activeManager.restart(payload?.pluginId)); handle(CHANNELS.uninstall, async (activeManager, payload) => activeManager.uninstall(payload?.pluginId)); + handle(CHANNELS.terminalTarget, async (_manager, target, event) => { + if (!options.interactionService) throw new Error("Host interactions unavailable"); + return options.interactionService.setTerminalTarget(event.sender, target); + }); handle(CHANNELS.themeCatalog, async () => { if (!options.themeService) throw new Error("Plugin themes are unavailable"); return options.themeService.catalog(); diff --git a/electron/plugins/runtime/runtimePeer.mjs b/electron/plugins/runtime/runtimePeer.mjs index 10d98e62b..81776d993 100644 --- a/electron/plugins/runtime/runtimePeer.mjs +++ b/electron/plugins/runtime/runtimePeer.mjs @@ -518,6 +518,10 @@ function createPluginContext(config, client, runtimeApi) { }, }; const terminals = { + shareSelection: (title) => { + if (!config.enabledFeatures?.includes("terminal.selection-sharing")) return Promise.reject(new Error("Terminal selection sharing is unsupported")); + return interact({ kind: "terminal.selection.read", title }); + }, onDidChange: runtimeApi.terminalEvents.event, }; const environment = { diff --git a/electron/plugins/terminalSelectionAuthority.cjs b/electron/plugins/terminalSelectionAuthority.cjs new file mode 100644 index 000000000..82d16f3f1 --- /dev/null +++ b/electron/plugins/terminalSelectionAuthority.cjs @@ -0,0 +1,67 @@ +"use strict"; +const {randomBytes,createHmac}=require('node:crypto'); +const {createDefinitionValidator}=require('./contractValidator.cjs'); +const {PluginRpcError,RPC_ERRORS}=require('./rpcRouter.cjs'); +const schema=require('./generated/plugin-contract.schema.json'); +const LIMITS=schema.$defs.TerminalSelectionSharingLimits.const; +const FEATURE=schema.$defs.TerminalSelectionSharingFeature.const; +const validateTarget=createDefinitionValidator('HostTerminalTarget'); +const fail=(code,message)=>new PluginRpcError(RPC_ERRORS[code],message); +/** Host-only resource authority. It never stores selected text or an endpoint DTO. */ +class TerminalSelectionAuthority { + constructor(options){ + this.getWindow=options.getWindow??(()=>null);this.getManager=options.getManager??(()=>null);this.clock=options.clock??Date.now; + this.key=randomBytes(32);this.target=null;this.handles=new Map();this.listeners=new Set();this.observed=null;this.disposables=[]; + this.timer=setInterval(()=>this.prune(),1000);this.timer.unref?.(); + } + onDidInvalidate(listener){this.listeners.add(listener);return{dispose:()=>this.listeners.delete(listener)};} + invalidate(){this.prune();for(const listener of this.listeners){try{listener();}catch{}}} + observe(manager){ + if(this.observed===manager)return; + for(const item of this.disposables)item?.dispose?.();this.disposables=[];this.observed=manager; + for(const method of ['onSessionOwned','onSessionClosed','onWorkerExit'])if(typeof manager?.[method]==='function')this.disposables.push(manager[method](()=>this.invalidate())); + } + setTarget(sender,payload){ + if(!validateTarget(payload))throw fail('invalidArgument','Invalid selected terminal target'); + if(!sender || this.getWindow()?.webContents!==sender || sender.isDestroyed?.())throw fail('permissionDenied','Selected terminal belongs to another window'); + if(this.target?.sender===sender && this.target.sessionId===payload.sessionId)return true; + this.target=payload.sessionId?{sender,sessionId:payload.sessionId}:null;this.invalidate();return true; + } + capture(sender,context){ + const features=[...(context.manifest?.features?.required??[]),...(context.manifest?.features?.optional??[])]; + if(!features.includes(FEATURE))throw fail('unsupported','Terminal selection sharing feature was not declared'); + const manager=this.getManager();this.observe(manager); + if(!this.target || this.target.sender!==sender)throw fail('failedPrecondition','Select a live terminal in the main window first'); + const {sessionId}=this.target;const binding=manager?.getPluginSessionBinding?.(sessionId,sender.id); + if(!binding)throw fail('unavailable','Selected terminal has no active owned worker connection'); + return Object.freeze({sender,manager,sessionId,epoch:binding.epoch,generation:binding.generation, + resource:`terminal-session:${sessionId}:window:${sender.id}:worker:${binding.epoch}:generation:${binding.generation}`}); + } + isCurrent(target){ + if(!target || this.target?.sender!==target.sender || this.target?.sessionId!==target.sessionId || target.sender.isDestroyed?.() || this.getManager()!==target.manager)return false; + const current=target.manager.getPluginSessionBinding(target.sessionId,target.sender.id); + return !!current && current.epoch===target.epoch && current.generation===target.generation; + } + assertCurrent(target){if(!this.isCurrent(target))throw fail('cancelled','Selected terminal connection or owner changed');} + prune(){for(const [token,entry]of this.handles)if(entry.expiresAt<=this.clock()||!this.isCurrent(entry.target))this.handles.delete(token);} + issue(target,context){ + this.assertCurrent(target);this.prune(); + if(this.handles.size>=LIMITS.handlesTotal || [...this.handles.values()].filter(e=>e.runtimeId===context.runtimeId).length>=LIMITS.handlesPerRuntime)throw fail('resourceExhausted','Terminal selection handle limit reached'); + const expiresAt=this.clock()+LIMITS.handleTtlMs,nonce=randomBytes(24).toString('base64url'); + const signature=createHmac('sha256',this.key).update(JSON.stringify([nonce,target.resource,context.pluginId,context.pluginVersion,context.runtimeId,context.securityPrincipal??null,expiresAt])).digest('base64url'); + const handle=`${nonce}.${signature}`; + this.handles.set(handle,{target,expiresAt,pluginId:context.pluginId,pluginVersion:context.pluginVersion,runtimeId:context.runtimeId,securityPrincipal:context.securityPrincipal}); + return {handle,expiresAt}; + } + resolve(handle,context){ + this.prune();const entry=this.handles.get(handle); + if(!entry || entry.pluginId!==context.pluginId || entry.pluginVersion!==context.pluginVersion || entry.runtimeId!==context.runtimeId || entry.securityPrincipal!==context.securityPrincipal)throw fail('permissionDenied','Terminal selection handle is unavailable'); + this.assertCurrent(entry.target);return entry.target; + } + releaseRuntime(runtimeId){for(const [key,entry]of this.handles)if(entry.runtimeId===runtimeId)this.handles.delete(key);} + releasePlugin(pluginId){for(const [key,entry]of this.handles)if(entry.pluginId===pluginId)this.handles.delete(key);} + releaseWindow(sender){if(this.target?.sender===sender)this.target=null;this.invalidate();} + clearHandles(){this.handles.clear();} + shutdown(){clearInterval(this.timer);for(const d of this.disposables)d?.dispose?.();this.handles.clear();this.listeners.clear();this.target=null;this.key.fill(0);} +} +module.exports={TerminalSelectionAuthority,FEATURE,LIMITS}; diff --git a/electron/preload/api.cjs b/electron/preload/api.cjs index 68c1f4eb6..408457eb0 100644 --- a/electron/preload/api.cjs +++ b/electron/preload/api.cjs @@ -122,6 +122,7 @@ function createPreloadApi(ctx) { }), restartPlugin: (pluginId) => ipcRenderer.invoke("netcatty:plugins:restart", { pluginId }), uninstallPlugin: (pluginId) => ipcRenderer.invoke("netcatty:plugins:uninstall", { pluginId }), + setPluginTerminalTarget: (target) => ipcRenderer.invoke("netcatty:plugins:terminal-target", target), getPluginThemes: () => ipcRenderer.invoke("netcatty:plugins:theme-catalog"), applyPluginTheme: (request) => ipcRenderer.invoke("netcatty:plugins:theme-apply", request), onPluginThemesChanged: (callback) => { diff --git a/global.d.ts b/global.d.ts index 49f74f65c..e936f6669 100644 --- a/global.d.ts +++ b/global.d.ts @@ -454,6 +454,7 @@ declare global { setPluginEnabled?(pluginId: string, enabled: boolean): Promise; restartPlugin?(pluginId: string): Promise; uninstallPlugin?(pluginId: string): Promise; + setPluginTerminalTarget?(target: import("@netcatty/plugin-contract").HostTerminalTarget): Promise; getPluginThemes?(): Promise; applyPluginTheme?(request: import("@netcatty/plugin-contract").ThemePackApplyRequest): Promise; onPluginThemesChanged?(callback: () => void): () => void; diff --git a/packages/plugin-cli/src/manifest.ts b/packages/plugin-cli/src/manifest.ts index d6dce01fc..1f9b09c71 100644 --- a/packages/plugin-cli/src/manifest.ts +++ b/packages/plugin-cli/src/manifest.ts @@ -369,6 +369,8 @@ function validateSemantics(manifest: PluginManifest): string[] { } const requiredFeatures = new Set(manifest.features?.required ?? []); + const allFeatures = new Set([...requiredFeatures, ...(manifest.features?.optional ?? [])]); + if ((manifest.permissions?.optional ?? []).some((p) => p === 'terminal.selection.read') && !allFeatures.has('terminal.selection-sharing')) errors.push('Terminal selection sharing requires terminal.selection-sharing'); 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..2e64b1b10 100644 --- a/packages/plugin-contract/schema/plugin-contract.schema.json +++ b/packages/plugin-contract/schema/plugin-contract.schema.json @@ -333,6 +333,9 @@ }, { "$ref": "#/$defs/HostClipboardWriteRequest" + }, + { + "$ref": "#/$defs/HostTerminalSelectionReadRequest" } ] }, @@ -369,6 +372,9 @@ }, { "const": true + }, + { + "$ref": "#/$defs/SharedTerminalSelection" } ] } @@ -479,6 +485,11 @@ "type": "string", "maxLength": 4096, "pattern": "^[^\\u0000]*$" + }, + "terminalSessionId": { + "type": "string", + "maxLength": 128, + "pattern": "^[A-Za-z0-9_-]+$" } }, "additionalProperties": false @@ -664,7 +675,8 @@ "provider.connection", "provider.authentication", "provider.sync", - "provider.importer" + "provider.importer", + "terminal.selection.read" ] }, "NonResourceScopedPermission": { @@ -698,7 +710,8 @@ "provider.connection", "provider.authentication", "provider.sync", - "provider.importer" + "provider.importer", + "terminal.selection.read" ] }, "ResourceScopedPermission": { @@ -770,9 +783,16 @@ "RequiredPermissionDeclaration": { "description": "Required resource-scoped permissions must name their complete activation-time approval bounds.", "oneOf": [ - { "$ref": "#/$defs/NonResourceScopedPermission" }, - { "$ref": "#/$defs/RequiredPermissionResourceDeclaration" } - ] + { + "$ref": "#/$defs/NonResourceScopedPermission" + }, + { + "$ref": "#/$defs/RequiredPermissionResourceDeclaration" + } + ], + "not": { + "const": "terminal.selection.read" + } }, "PermissionSet": { "type": "object", @@ -3058,6 +3078,77 @@ "entries", "diagnostics" ] + }, + "TerminalSelectionSharingFeature": { + "const": "terminal.selection-sharing" + }, + "TerminalSelectionSharingLimits": { + "const": { + "textBytes": 4096, + "handleTtlMs": 120000, + "handlesPerRuntime": 4, + "handlesTotal": 64 + } + }, + "HostTerminalTarget": { + "type": "object", + "properties": { + "sessionId": { + "type": [ + "string", + "null" + ], + "maxLength": 128, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "HostTerminalSelectionReadRequest": { + "type": "object", + "properties": { + "kind": { + "const": "terminal.selection.read" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 256 + } + }, + "required": [ + "kind", + "title" + ], + "additionalProperties": false + }, + "SharedTerminalSelection": { + "type": "object", + "properties": { + "text": { + "type": "string", + "minLength": 1, + "maxLength": 4096, + "pattern": "^[^\\u0000]*$" + }, + "handle": { + "type": "string", + "minLength": 64, + "maxLength": 256 + }, + "expiresAt": { + "$ref": "#/$defs/SafePositiveInteger" + } + }, + "required": [ + "text", + "handle", + "expiresAt" + ], + "additionalProperties": false } } } diff --git a/packages/plugin-contract/src/generated/plugin-contract.ts b/packages/plugin-contract/src/generated/plugin-contract.ts index 032267102..87ff0730a 100644 --- a/packages/plugin-contract/src/generated/plugin-contract.ts +++ b/packages/plugin-contract/src/generated/plugin-contract.ts @@ -205,9 +205,10 @@ export type HostInteractionPrompt = { phase: "request" | "preview"; request: HostInteractionRequest; previewText?: string; + terminalSessionId?: string; }; -export type HostInteractionRequest = (HostQuickPickRequest) | (HostInputRequest) | (HostClipboardReadRequest) | (HostClipboardWriteRequest); +export type HostInteractionRequest = (HostQuickPickRequest) | (HostInputRequest) | (HostClipboardReadRequest) | (HostClipboardWriteRequest) | (HostTerminalSelectionReadRequest); export type HostInteractionResponse = { requestId: string; @@ -220,7 +221,7 @@ export type HostInteractionResult = ({ cancelled: true; }) | ({ cancelled: false; - value: (string) | (true); + value: (string) | (true) | (SharedTerminalSelection); }); export type HostQuickPickItem = { @@ -237,6 +238,15 @@ export type HostQuickPickRequest = { export type HostSingleLineInputText = string; +export type HostTerminalSelectionReadRequest = { + kind: "terminal.selection.read"; + title: string; +}; + +export type HostTerminalTarget = { + sessionId: string | null; +}; + export type IconReference = (ThemeIcon) | (PackageIcon); export type ImporterDetectPayload = { @@ -431,7 +441,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" | "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" | "terminal.selection.read"; export type NullableRpcId = (RpcId) | (null); @@ -587,7 +597,7 @@ 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" | "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" | "terminal.selection.read"; export type PluginViewFocusEvent = { instanceId: string; @@ -811,6 +821,12 @@ export type SettingOption = { export type SettingScope = "application" | "workspace" | "host" | "session" | "device"; +export type SharedTerminalSelection = { + text: string; + handle: string; + expiresAt: SafePositiveInteger; +}; + export type StreamChunkByteLength = number; export type StreamChunkData = ({ @@ -1029,6 +1045,10 @@ export type TerminalInterceptorReadyFrame = { export type TerminalInterceptorWindowBytes = number; +export type TerminalSelectionSharingFeature = "terminal.selection-sharing"; + +export type TerminalSelectionSharingLimits = {"textBytes":4096,"handleTtlMs":120000,"handlesPerRuntime":4,"handlesTotal":64}; + export type TerminalSessionSnapshot = { sessionId: string; hostId?: string; diff --git a/packages/plugin-contract/src/index.ts b/packages/plugin-contract/src/index.ts index 4afd81bef..f348c4390 100644 --- a/packages/plugin-contract/src/index.ts +++ b/packages/plugin-contract/src/index.ts @@ -60,3 +60,5 @@ export const PLUGIN_TERMINAL_SIDEBAR_FEATURE = "views.terminal-sidebar" as const export const PLUGIN_INTERACTIVE_COMMAND_FEATURE = "commands.interactive" as const satisfies import("./generated/plugin-contract.js").InteractiveCommandFeature; export const PLUGIN_THEME_PACK_FEATURE = "appearance.theme-packs" as const satisfies import("./generated/plugin-contract.js").ThemePackFeature; + +export const PLUGIN_TERMINAL_SELECTION_SHARING_FEATURE = "terminal.selection-sharing" as const satisfies import("./generated/plugin-contract.js").TerminalSelectionSharingFeature; diff --git a/packages/plugin-sdk/src/index.ts b/packages/plugin-sdk/src/index.ts index 4aa74cc80..e07993cee 100644 --- a/packages/plugin-sdk/src/index.ts +++ b/packages/plugin-sdk/src/index.ts @@ -45,6 +45,7 @@ import type { SyncWriteObjectPayload, SyncWriteObjectResult, TerminalSessionSnapshot, + SharedTerminalSelection, } from "@netcatty/plugin-contract"; export type * from "@netcatty/plugin-contract"; @@ -626,6 +627,8 @@ export type SyncProviderHandler = Readonly<{ }>; export interface PluginTerminalSessions { + /** Explicit host Preview then Share; no screen/history query or automatic read. */ + shareSelection(title: string): Promise; onDidChange(listener: (event: TerminalSessionEvent) => void): Disposable; } @@ -935,3 +938,5 @@ export { PLUGIN_TERMINAL_SIDEBAR_FEATURE } from "@netcatty/plugin-contract"; export { PLUGIN_INTERACTIVE_COMMAND_FEATURE } from "@netcatty/plugin-contract"; export { PLUGIN_THEME_PACK_FEATURE } from "@netcatty/plugin-contract"; + +export { PLUGIN_TERMINAL_SELECTION_SHARING_FEATURE } from "@netcatty/plugin-contract";