docs: complete project research

Add STACK, FEATURES, ARCHITECTURE, PITFALLS, and SUMMARY research files for Ready2Blob.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-26 09:46:22 +01:00
co-authored by Claude Sonnet 4.6
parent da8b950684
commit 0b72904e36
5 changed files with 1308 additions and 0 deletions
+362
View File
@@ -0,0 +1,362 @@
# Domain Pitfalls
**Domain:** rclone config generator / PowerShell deployment wizard (Windows/Intune/RMM)
**Researched:** 2026-03-26
**Confidence:** HIGH (Intune/PowerShell — verified against official Microsoft docs), MEDIUM (rclone-specific — based on format spec knowledge plus training data; rclone docs were inaccessible during research)
---
## Critical Pitfalls
Mistakes that cause the generated script/config to silently fail or require a full rewrite.
---
### Pitfall 1: rclone config deployed to wrong path under SYSTEM context
**What goes wrong:**
When Intune deploys a PowerShell script with "Run as SYSTEM" (the `No` logged-on-credentials option), the script runs as `NT AUTHORITY\SYSTEM`. The default rclone config location resolves from the SYSTEM user's `%APPDATA%`, which is `C:\Windows\system32\config\systemprofile\AppData\Roaming\rclone\rclone.conf`. This path is not readable by the end user who will later run rclone interactively. The config is deposited silently with no error, but rclone launched by the user finds no config.
**Why it happens:**
rclone resolves config location from environment variables at runtime. Under SYSTEM, `%APPDATA%` and `%USERPROFILE%` expand to the SYSTEM profile paths, not any individual user's profile. Developers test locally as themselves and never hit this path.
**Consequences:**
- rclone runs with no configuration; all sync commands fail with "no remote" error
- Hard to debug because the config file exists on disk — just in the wrong place
- If the wizard generates a hardcoded `%APPDATA%` path string in the script, that string is evaluated at deployment time (SYSTEM), not at user runtime
**Prevention:**
- The generated script must write the config to a machine-wide path such as `C:\ProgramData\rclone\rclone.conf` and then invoke rclone with `--config "C:\ProgramData\rclone\rclone.conf"` (or set `RCLONE_CONFIG` env var).
- Alternatively: write to each user's profile by running in user context — but SYSTEM context is common for silently deploying software.
- The wizard should make the config destination path explicit and let the IT admin choose: machine-wide vs. user-profile. Never default to a bare `%APPDATA%` expansion in a SYSTEM-context script.
**Detection:**
- Config exists at SYSTEM profile path but rclone launched by user says "no remote configured"
- Check `rclone config file` — it will show the wrong path
**Phase relevance:** Phase generating the PowerShell script (any phase touching script output)
---
### Pitfall 2: Intune PowerShell scripts are size-limited to 200 KB (ASCII)
**What goes wrong:**
Microsoft Intune enforces a hard 200 KB (ASCII) size limit on uploaded PowerShell scripts. Scripts that embed a large rclone installer binary (base64-encoded), or that inline multiple large config payloads, will be rejected at upload time.
**Why it happens:**
IT developers prototype a "self-contained" script that downloads rclone, unpacks it, writes the config, and sets up a scheduled task — all in one file. Base64-encoding a ~50 MB rclone binary produces a ~67 MB string. Even base64-encoding a 400 KB installer produces a 550 KB string, well over the limit.
**Consequences:**
- Script upload fails; IT admin gets a non-obvious error in Intune
- Workaround requires restructuring the entire script delivery approach
**Prevention:**
- The wizard must never embed rclone binary content into the generated script
- The rclone installation step must use a network download (e.g., `Invoke-WebRequest` from the rclone GitHub releases API or a corporate file share URL) or reference a Win32 app deployment separately
- Clearly surface this constraint in the wizard: "rclone binary will be downloaded from [URL] at deployment time" — and let the admin specify an internal mirror if internet access is restricted on endpoints
**Detection:**
- Intune admin center shows upload error "Script size exceeds limit"
- Script file is visibly large before upload
**Phase relevance:** Phase implementing the rclone-install option in script generation
---
### Pitfall 3: PowerShell script encoding mismatch causes silent config corruption
**What goes wrong:**
The generated PowerShell script writes the rclone config file to disk using `Set-Content` or `Out-File`. The default encoding in Windows PowerShell 5.1 is UTF-16 LE with BOM for `Out-File`, and varies for `Set-Content` (system codepage/ANSI on PS 5.1, UTF-8 no-BOM on PS 7+). rclone expects its config file in UTF-8. A config with a UTF-16 BOM or ANSI-encoded special characters (common in storage keys) will be misread, causing authentication failures.
**Why it happens:**
Developers write `Out-File $configPath` and it works in their test because all values are ASCII. The bug surfaces when a customer has a storage account key or SAS token containing characters that differ between encodings, or when the file has a BOM that confuses rclone's parser.
**Consequences:**
- rclone silently reads a corrupt config; authentication fails with opaque errors
- Hard to reproduce because it only manifests with certain key contents
**Prevention:**
- The generated script must always write the config with explicit UTF-8 no-BOM encoding:
```powershell
[System.IO.File]::WriteAllText($configPath, $configContent, [System.Text.Encoding]::UTF8)
```
or
```powershell
Set-Content -Path $configPath -Value $configContent -Encoding UTF8
```
Note: In PowerShell 5.1, `-Encoding UTF8` writes UTF-8 *with* BOM. Use `[System.IO.File]::WriteAllText` with `new System.Text.UTF8Encoding($false)` to guarantee no BOM.
- The wizard's script template must hardcode the correct write method; never leave encoding to PS default
**Detection:**
- Open the written config in a hex editor: UTF-16 has `FF FE` as first bytes; UTF-8 BOM has `EF BB BF`
- rclone error: "unexpected character at start of file" or authentication failures on otherwise valid credentials
**Phase relevance:** Any phase producing the PowerShell script template
---
### Pitfall 4: rclone config section names collide with rclone reserved names or contain invalid characters
**What goes wrong:**
rclone remote names in the config are used on the command line as `remotename:path`. The name becomes part of shell arguments and rclone's internal addressing. Names with spaces, colons, forward slashes, or square brackets break the INI section header (`[remote name]` is valid INI only if the name contains no `]`). Names that match rclone built-in remote types (e.g., naming a remote "local", "union", "memory") cause confusing errors. Names starting with a dash conflict with CLI flag parsing.
**Why it happens:**
The wizard lets IT admins freely type a remote name without validation. The name goes into `[user input]` verbatim.
**Consequences:**
- Config is syntactically broken (rclone fails to parse)
- Or config parses but the remote cannot be referenced on the command line
- Error messages are cryptic: "Failed to create file system for remotename: didn't find section in config file"
**Prevention:**
- Validate remote names in the wizard UI before generation: allow only `[a-zA-Z0-9_-]`, max ~40 chars, no leading dash
- Show a live preview of the section header: `[my-remote]`
- Reject reserved-looking names or warn on them
**Detection:**
- rclone returns "didn't find section in config file" when the name contains special characters
- rclone returns parse error when name contains `]`
**Phase relevance:** Wizard input validation phase; config generation phase
---
### Pitfall 5: Secrets embedded in generated scripts are exposed in Intune admin center logs
**What goes wrong:**
Intune logs PowerShell script output and stores it in the Azure portal (AgentExecutor.log on endpoint + reporting in Intune admin center). If the generated script echoes the config content or uses `Write-Host` with credential values for debugging, those secrets are persisted in logs accessible to any Intune admin.
**Why it happens:**
Developers add debug output during testing ("Writing config: [content]") and forget to remove it. Or error handlers dump the config on failure.
**Consequences:**
- Storage account keys, SAS tokens, or OAuth secrets appear in Intune reporting
- Violates least-privilege and secrets hygiene; potential audit/compliance failure
**Prevention:**
- The wizard's generated script template must never echo credential values
- Use a sentinel like `Write-Host "Writing config to $configPath"` (path only, no content)
- Add a comment in the generated script: `# Do not add Write-Host or logging for $configContent`
- The wizard UI must display a security warning at download time (already planned per PROJECT.md)
**Detection:**
- Audit the script template for any interpolation of credential variables into strings passed to output cmdlets
**Phase relevance:** Script template design (early phase); security review before any release
---
## Moderate Pitfalls
---
### Pitfall 6: Group Policy overrides PowerShell execution policy set in the script
**What goes wrong:**
The generated script attempts to set `Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned` or `Bypass`. In enterprise environments with Group Policy managing `MachinePolicy` or `UserPolicy` execution policy scopes, the script's `Set-ExecutionPolicy` call has no effect — Group Policy always wins. The script appears to succeed (no error from `Set-ExecutionPolicy`) but subsequent script logic may still fail if the endpoint GP enforces `AllSigned` or `Restricted`.
**Why it happens:**
Official Microsoft docs confirm: "Set-ExecutionPolicy doesn't override a Group Policy, even if the user preference is more restrictive than the policy." Intune itself bypasses execution policy for its own scripts (IME uses `-ExecutionPolicy Bypass` internally), but any child processes spawned by the script inherit the GP-enforced policy.
**Consequences:**
- Scripts that call `& rclone.exe` or invoke helper `.ps1` files from within the script fail with execution policy errors
- Developers test on unmanaged machines and never observe GP interference
**Prevention:**
- The generated script should not attempt to change execution policy
- Any sub-scripts should be invoked with `-ExecutionPolicy Bypass` in the powershell.exe call, or avoided entirely (inline everything)
- Document this in the wizard's "Intune deployment" output pane
**Detection:**
- `Get-ExecutionPolicy -List` on target machine shows `MachinePolicy = AllSigned`
- Script works in test but fails on managed fleet endpoints
**Phase relevance:** Script generation phase; testing guidance
---
### Pitfall 7: 32-bit vs 64-bit PowerShell host affects path resolution
**What goes wrong:**
Intune's default is to run scripts in the 32-bit PowerShell host (`Run script in 64-bit PowerShell host = No`). On 64-bit Windows, 32-bit processes use File System Redirector: `System32` resolves to `SysWOW64`, and `%ProgramFiles%` resolves to `%ProgramFiles(x86)%`. If the generated script installs rclone to `$env:ProgramFiles\rclone\` under 32-bit context, the binary lands in `C:\Program Files (x86)\rclone\`, not `C:\Program Files\rclone\`. When the user runs rclone from a 64-bit shell, they look in `Program Files` and find nothing.
**Why it happens:**
The Intune "Run in 64-bit" option defaults to `No` per Microsoft docs. Developers test in a normal 64-bit PowerShell session.
**Consequences:**
- rclone binary installed to wrong Program Files variant
- PATH entries or shortcuts point to non-existent location
**Prevention:**
- The generated script should use `$env:ProgramW6432` (always the native 64-bit Program Files on 64-bit Windows) or hardcode `C:\Program Files\rclone\`
- The wizard UI for Intune output should recommend enabling "Run script in 64-bit PowerShell host" and document why
- Alternatively, use `C:\ProgramData\rclone\` which is not subject to WOW64 redirection
**Detection:**
- rclone binary absent from expected path after deployment
- `[System.Environment]::Is64BitProcess` returns `False` inside the running script
**Phase relevance:** Script generation phase; Intune deployment option
---
### Pitfall 8: OAuth-backed backends require interactive browser flow — incompatible with SYSTEM/headless deployment
**What goes wrong:**
rclone backends that use OAuth (OneDrive, Google Drive, Dropbox, Box, etc.) require an interactive browser authorization step to generate the token. The rclone config for these backends includes an `token = {...}` JSON blob. If the IT admin generates a config without pre-populating this token, the deployment script writes a config with no token. When rclone first runs on the endpoint, it attempts an interactive browser flow — which silently fails or hangs in a SYSTEM/headless context.
**Why it happens:**
The wizard generates the config from form inputs. For OAuth backends, the wizard cannot complete the OAuth flow on behalf of the user — there is no rclone running in the browser context to perform `rclone config`. The IT admin might not realize the token needs to be obtained separately on a reference machine.
**Consequences:**
- Deployed rclone silently does nothing or opens a browser on the endpoint
- Most prominent with OneDrive; affects any backend requiring `rclone authorize`
**Prevention:**
- For OAuth backends, the wizard must show a prominent notice: "This backend requires an OAuth token. You must run `rclone config` or `rclone authorize` on a reference Windows machine as the target user, then copy the resulting token value into this wizard."
- The wizard should provide a dedicated "OAuth token" input field for token-based backends, with instructions for how to extract the token from `rclone config show remotename`
- Consider warning against deploying OAuth backends via SYSTEM-context Intune scripts entirely; recommend user-context deployment instead
**Detection:**
- Config section for OneDrive/GDrive has no `token =` line
- rclone first-run opens a browser on the endpoint or exits with "no token found"
**Phase relevance:** Backend-specific configuration phase; wizard backend selection step
---
### Pitfall 9: SAS tokens and storage keys contain characters that need escaping in INI values
**What goes wrong:**
Azure SAS tokens contain `%`, `=`, `&`, and `+` characters. Azure storage keys contain `+` and `/` and end in `==`. In rclone's INI config format, values are read until end-of-line — no quoting needed for most characters — but if the value accidentally contains a line-break (e.g., from copy-paste in a browser field that wraps), the config is truncated silently. If the generated value is also used inside a PowerShell string interpolation (e.g., `"sas_url = $sasToken"`), PowerShell variable substitution can corrupt values containing `$`.
**Why it happens:**
The wizard builds the config as a JavaScript template literal. Storage keys and SAS tokens pasted by users may include trailing newlines or spaces. PowerShell double-quoted strings treat `$` as variable prefix.
**Consequences:**
- Truncated SAS token causes authentication failures with opaque Azure storage errors
- Corrupted key causes "AuthenticationFailed" from Azure
**Prevention:**
- Trim all credential inputs in the wizard before inserting into the config (strip leading/trailing whitespace including `\n`, `\r`)
- In the PowerShell script template, use single-quoted strings for the config content (PowerShell single-quoted strings do not interpolate `$`):
```powershell
$configContent = @'
[myremote]
type = azureblob
account = mystorageaccount
key = ABC+xyz==
'@
```
(here-string with single-quote terminator)
- Validate that credential inputs do not contain newlines before generating
**Detection:**
- Config file, when opened, shows a truncated key value
- rclone error: "failed to parse config file" or Azure "AuthenticationFailed"
**Phase relevance:** Config generation logic (core phase)
---
### Pitfall 10: Windows path length limit (MAX_PATH = 260) breaks rclone operations on deep directory trees
**What goes wrong:**
On Windows versions before Windows 10 1607, and on any Windows where the Long Path registry key is not set, paths exceeding 260 characters cause rclone operations to fail silently or with cryptic I/O errors. rclone syncing deep SharePoint or OneDrive folder trees commonly hits this. The deployment script may also fail if it writes files to paths that are too long (e.g., user profile paths with long usernames inside long corporate folder structures).
**Why it happens:**
Windows enforces MAX_PATH = 260 by default per `kernel32.dll`. IT admins don't control the endpoint's registry setting. The wizard generates scripts without path-length guards.
**Consequences:**
- rclone skips or errors on files with long paths
- `New-Item` or `Set-Content` in the PowerShell script itself can fail if the config destination path is long
**Prevention:**
- The wizard should recommend using `C:\ProgramData\rclone\` (short path) for config and binary placement, not user-profile paths
- Generated scripts should include a check and optionally enable long paths:
```powershell
Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
```
(requires admin rights; typically available in SYSTEM context)
- Document the limitation in the wizard output pane for Intune deployments
**Detection:**
- rclone logs show `ERROR: ... path too long`
- PowerShell script itself fails with "The specified path, file name, or both are too long"
**Phase relevance:** Script generation; deployment documentation phase
---
## Minor Pitfalls
---
### Pitfall 11: Intune script runs once per device; config changes don't re-deploy unless script is modified
**What goes wrong:**
Intune only re-runs a PowerShell script if the script content changes or is reassigned. If the IT admin generates a new config (different credentials, different remote name) and wants to update the deployed config, they must upload a new version of the script to Intune. If they upload the exact same script bytes with only a comment changed, the re-run is triggered. But if they don't know this, they think re-assigning the unchanged script will update endpoints — it won't.
**Prevention:**
- Document this in the wizard output: "To update config on endpoints, modify and re-upload the script (e.g., bump a version comment) to trigger Intune re-execution."
- Consider auto-inserting a `# Generated: [timestamp]` comment in each script so re-generated scripts always differ
**Phase relevance:** Documentation/UX phase
---
### Pitfall 12: rclone binary download URL in the script becomes stale
**What goes wrong:**
The generated script contains a hardcoded rclone download URL (e.g., `https://downloads.rclone.org/rclone-current-windows-amd64.zip`). rclone uses the filename `rclone-current-*` as a redirect alias. This URL is stable, but if the wizard hardcodes a specific version URL (e.g., `v1.68.0`) to ensure repeatability, that version URL remains functional but the binary may have known issues. If the wizard uses `current`, the binary silently upgrades, potentially introducing breaking changes.
**Prevention:**
- Use the `rclone-current-windows-amd64.zip` alias for the default path (always latest stable)
- Allow an override field for IT admins who want to pin a version
- Add a comment in the generated script stating the resolved version strategy
**Phase relevance:** Script generation (rclone install option)
---
### Pitfall 13: Generated config has Windows-style line endings that cause issues on cross-platform rclone use
**What goes wrong:**
JavaScript running in a browser on Windows may produce `\r\n` line endings when building the config string (less likely with modern JS but possible with string concatenation involving platform newlines). rclone's INI parser handles `\r\n` correctly on Windows, but if the config is later copied to a Linux/macOS system, the `\r` characters appear in values.
**Prevention:**
- Explicitly normalize line endings to `\n` in the config generation logic before download
- Use `content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')` before creating the Blob for download
**Phase relevance:** Config generation (frontend logic)
---
## Phase-Specific Warnings
| Phase Topic | Likely Pitfall | Mitigation |
|-------------|---------------|------------|
| Script template design | SYSTEM context config path mismatch (Pitfall 1) | Use machine-wide path; document context options |
| rclone install option | 200 KB Intune script size limit (Pitfall 2) | Download-only; never embed binary |
| Script file write logic | PowerShell encoding writes UTF-16 BOM (Pitfall 3) | Use `[System.IO.File]::WriteAllText` with explicit UTF-8 no-BOM |
| Remote name input field | Invalid characters in section name (Pitfall 4) | Validate `[a-zA-Z0-9_-]` in UI before generation |
| Debug/error output in script | Secrets exposed in Intune logs (Pitfall 5) | No credential interpolation in output cmdlets |
| Execution policy in script | GP overrides any Set-ExecutionPolicy call (Pitfall 6) | Do not set policy; use `-ExecutionPolicy Bypass` on sub-processes |
| Intune script options | 32-bit host path redirection (Pitfall 7) | Use `$env:ProgramW6432` or `C:\ProgramData\rclone\` |
| OAuth backend config | Headless OAuth flow impossible (Pitfall 8) | Require pre-obtained token; prominent wizard warning |
| Credential input handling | SAS/key corruption via whitespace or `$` (Pitfall 9) | Trim inputs; single-quoted PowerShell here-strings |
| Config/binary placement | MAX_PATH exceeded on deep trees (Pitfall 10) | Short machine-wide paths; optionally enable long paths |
| Re-deployment UX | Intune won't re-run identical script (Pitfall 11) | Auto-insert timestamp comment; document update flow |
| rclone download URL | Pinned URL goes stale (Pitfall 12) | Default to `rclone-current`; allow version override |
| Config string generation | Windows CRLF in config file (Pitfall 13) | Normalize to LF before Blob creation |
---
## Sources
- Microsoft Learn — PowerShell scripts in Intune (updated 2025-10-02): https://learn.microsoft.com/en-us/intune/intune-service/apps/powershell-scripts
- Microsoft Learn — Intune Management Extension (updated 2026-03-17): https://learn.microsoft.com/en-us/intune/intune-service/apps/intune-management-extension
- Microsoft Learn — Set-ExecutionPolicy reference (updated 2025-04-15): https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy
- Microsoft Learn — Naming Files, Paths, and Namespaces (Win32): https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
- Microsoft Learn — Code Page Identifiers: https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers
- rclone config format and Windows behavior: training data (MEDIUM confidence; rclone official docs were inaccessible during research session — verify against https://rclone.org/docs/ before finalizing)