Skip to content

Toolbox management: list, upload, delete, and elevated/silent runs - #37

Merged
christaylorcodes merged 5 commits into
masterfrom
feature/toolbox-management
Nov 12, 2026
Merged

christaylorcodes merged 5 commits into
masterfrom
feature/toolbox-management

Conversation

@christaylorcodes

@christaylorcodes christaylorcodes commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Pull Request

Description

Adds Toolbox management to the module. Until now it could only queue an existing Toolbox item on a session; this adds listing, uploading and deleting items, and the two other run modes the server offers. Ships in 0.5.0 (35 commands).

Related Issue

None. The 401 hint relates to #31.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • Refactoring / tests

Changes Made

New functions (credentials connections only):

  • Get-CWCToolbox lists the Toolbox as one object per folder and file, with Path, Name, IsFolder and Attributes (PageService.GetToolbox). -Raw returns the server's tree.
  • Add-CWCToolboxItem uploads a file to the shared Toolbox in chunks (512 KB by default, -ChunkSize up to 4 MB), or creates a folder with -Directory (ToolboxService.WriteToolboxFileContent). It replaces an item of the same name, and the confirmation text says so. If the upload fails or is stopped after the first chunk, the incomplete item is deleted so it cannot be run; a failure on the first chunk only warns.
  • Remove-CWCToolboxItem deletes a Toolbox file or folder (ToolboxService.ProcessToolboxOperation, Delete). It asks for confirmation by default. Afterwards it lists the Toolbox and returns CWC.ToolboxItemNotRemoved when the item is still there, because the server answers success even when it could not delete a file it has open.

Changes to existing behaviour:

  • Send-CWCToolboxItem gains -Elevated (QueuedElevatedTool, 101) and -Silent (QueuedSilentElevatedTool, 117). Both ask for confirmation unless -Confirm:$false is passed, and both return CWC.AuthModeMismatch on an API-secret connection.
  • Fix: six commands sent their request when the confirmation prompt could not be shown (for example under -NonInteractive): Remove-CWCToolboxItem, Add-CWCToolboxItem, Send-CWCToolboxItem, Remove-CWCHostFromSession, Add-CWCSessionNote and Send-CWCSessionMessage. They now stop, and a module test rejects the pattern that caused it.
  • A 401 "Needs permission" on a credentials connection adds a hint to run Connect-CWC -Force (also for MFA connections).
  • Connect-CWC marks a credentials connection as LoggingIn during its validation call, so that hint is not added to a failed login.

Supporting changes:

  • Private/Resolve-CWCToolboxPath.ps1 normalises Toolbox paths and refuses, before any request, a path that could name the Toolbox root, its parent or another drive, a Windows device name (CON, NUL, COM1...) or a part longer than 255 characters.
  • ToolboxService added to the services Invoke-CWCServiceMethod accepts; $script:CWCToolboxOperation and two session event numbers added to source/prefix.ps1.
  • AGENTS.md, README.md, CHANGELOG.md (notes under [0.5.0]) and the generated help are updated.

Things a reviewer should know:

  • The machine opens a Toolbox item the way Windows opens a file, so a .ps1 opens in its default program instead of running.
  • Use -Silent for unattended runs. An -Elevated item was queued but did not start on a machine with no host connected.
  • The server keeps a file open for a few minutes after it is queued to run; a delete in that time leaves it and now returns CWC.ToolboxItemNotRemoved.
  • Not done here: automatic re-sign-in when the server drops a login's management permissions, and upload to a temporary name followed by a move.

Testing

  • ./Tests/test-local.ps1 passes (analyzer, manifest, Pester on PS 7 and 5.1, docs drift)
  • Tested against a live ScreenConnect server (if applicable)

594 Pester tests pass on PowerShell 7.6 and Windows PowerShell 5.1; PSScriptAnalyzer reports 0 errors.

Against a live on-premises server (2026-11-11 and 2026-11-12), in throwaway folders that were removed afterwards:

Check Result
Get-CWCToolbox, nested folders and files Pass
Upload of a small top-level file Pass
Upload into a folder that already has files (PS 7 and 5.1) Pass: the existing files stayed
Three-chunk upload, 1.3 MB (PS 7 and 5.1) Pass: SHA256 of the copy the machine downloaded equals the local file
Remove-CWCToolboxItem on a file and on a folder (PS 7 and 5.1) Pass
Delete of a missing item Server answers HTTP 500 "Cannot edit virtual toolbox item"
Delete of a folder holding a file the server has open Server answers success and keeps the file; the command returns CWC.ToolboxItemNotRemoved; a retry about two minutes later removed it
Send-CWCToolboxItem, standard mode Pass
Send-CWCToolboxItem -Silent, top-level item and items in a folder (/ and \) Pass: ran as NT AUTHORITY\SYSTEM
Send-CWCToolboxItem -Elevated Event 101 was queued; the item did not start on a machine with no host connected. Not tested with a host connected

The event numbers (101, 117) and the ToolboxOperation values were read from the web client's SC.types on that server.

Checklist

  • Code follows project conventions (AGENTS.md)
  • Tests cover new/changed behavior
  • PSScriptAnalyzer reports zero errors
  • CHANGELOG.md updated (if applicable)
  • Documentation updated (if applicable)
  • New public function is in source/Public/ (the build exports it; no manifest edit) and has comment-based help

🤖 Generated with Claude Code

Chris Taylor and others added 3 commits November 12, 2026 10:14
- Get-CWCToolbox lists the Toolbox as one object per folder and file
  with its path (PageService.GetToolbox); -Raw returns the server tree
- Add-CWCToolboxItem uploads a file to the shared Toolbox in chunks, or
  creates a folder (ToolboxService.WriteToolboxFileContent); accepts
  files from the pipeline
- Remove-CWCToolboxItem deletes a Toolbox file or folder
  (ToolboxService.ProcessToolboxOperation, Delete)
- Send-CWCToolboxItem gains -Elevated (QueuedElevatedTool 101) and
  -Silent (QueuedSilentElevatedTool 117, runs as SYSTEM); credentials
  connections only
- Toolbox paths are normalized and checked before they are sent, so a
  path that could name the Toolbox root, its parent or another drive is
  refused
- A 401 "Needs permission" on a credentials connection now suggests
  Connect-CWC -Force: the server stops honouring an older login's
  management permissions while ordinary calls keep working

Event and operation numbers were read from the web client of a live
server; listing, upload and the silent run were exercised against it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add-CWCToolboxItem deletes an incomplete item when a later chunk fails
or the upload is stopped, says that it replaces an item, and caps
-ChunkSize at 4 MB. Toolbox paths refuse device names and long parts.

Send-CWCToolboxItem -Elevated and -Silent ask for confirmation.

A confirmation prompt that cannot be shown now stops the command in
Remove-CWCToolboxItem, Add-CWCToolboxItem, Send-CWCToolboxItem,
Remove-CWCHostFromSession, Add-CWCSessionNote and Send-CWCSessionMessage;
they went on and sent the request.

The 401 hint on an MFA connection names Connect-CWC -Force.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Move the Toolbox notes into the 0.5.0 section (35 commands), list the
commands that ask for confirmation in the README and the about topic,
and regenerate the help after the rebase.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@christaylorcodes
christaylorcodes force-pushed the feature/toolbox-management branch from 00ac838 to 4e9d942 Compare November 12, 2026 17:17
christaylorcodes and others added 2 commits November 12, 2026 10:22
Add-CWCToolboxItem warns when the first chunk fails with the item's state
unknown, and refuses -Directory:$false instead of creating a folder.
A module test rejects an early return on a negated ShouldProcess call.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Remove-CWCToolboxItem lists the Toolbox after the delete and returns
CWC.ToolboxItemNotRemoved when the item is still there. Seen live: the
server answers success and keeps a file it has open.
Document that an -Elevated item did not start without a host connected.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@christaylorcodes
christaylorcodes merged commit b90f466 into master Nov 12, 2026
6 checks passed
@christaylorcodes
christaylorcodes deleted the feature/toolbox-management branch November 12, 2026 21:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant