Cloak Files for Nextcloud

Last Updated: 2026-03-10 App Version: 1.0.0

Overview#

Cloak Files is a lightweight Nextcloud companion app that adds PII anonymization directly into the Nextcloud Files interface. With a sidebar tab and a right-click context menu action, you can analyze and anonymize text files without leaving the Files app.

Cloak Files is designed to work alongside the Cloak Anonymizer app but can also be installed independently.

Key Features#

Sidebar Tab -- A dedicated "Cloak" tab in the file details sidebar for quick PII analysis and anonymization
Right-Click File Action -- "Anonymize with Cloak" context menu on any supported text file
Shared Configuration -- Automatically reads the API key from Cloak Anonymizer if both apps are installed
Lightweight -- No navigation entry, no full-page UI. Just two integration points in Nextcloud Files

Requirements#

Nextcloud 28, 29, 30, or 31
PHP 8.1 or higher
PHP extensions: json, mbstring, xml, curl
cloak.business account with API key (get one free)
Server with outbound HTTPS access to cloak.business

Installation#

Manual Installation#

Download cloak_files-v1.0.0.tar.gz from the releases page

Extract to your Nextcloud custom_apps/ directory:

cd /var/www/nextcloud/custom_apps
tar xzf cloak_files-v1.0.0.tar.gz

Set correct permissions:

chown -R www-data:www-data cloak_files/

Enable the app:

sudo -u www-data php /var/www/nextcloud/occ app:enable cloak_files

Configuration#

With Cloak Anonymizer installed (recommended)#

If both Cloak Anonymizer and Cloak Files are installed, Cloak Files automatically reads the API key from Cloak Anonymizer. No separate configuration is needed.

Standalone configuration#

If only Cloak Files is installed:

Go to Settings > Personal > Security
Find the Cloak Files section
Enter your API URL (default: https://cloak.business) and API key (cb_...)
Click Save Settings

Using the Sidebar Tab#

Open any text file in Nextcloud Files
Click the file row or the "..." menu, then select "Open details" to open the sidebar
Click the "Cloak" tab in the sidebar
The file content loads automatically
Click Analyze to detect PII entities
Review detected entities with confidence scores
Select an anonymization method per entity type
Click Anonymize to process
Choose to save as a new file or overwrite the original

Using the Right-Click Action#

Navigate to Files in Nextcloud
Right-click any supported text file
Select "Anonymize with Cloak" from the context menu
The Cloak Anonymizer app opens with the file pre-loaded in the Anonymize tab

Note: The right-click action requires the Cloak Anonymizer app to be installed. It opens the full Anonymizer UI with the selected file's content already loaded.

Supported File Types#

The sidebar and right-click action work with text-based files:

Format	Extension
Plain Text	.txt
CSV	.csv
HTML	.html
Markdown	.md
XML	.xml
JSON	.json
YAML	.yaml, .yml
Source Code	Any text/* MIME type

Maximum file size: 10 MB

Architecture#

Nextcloud Files UI          Nextcloud Server              cloak.business API
+------------------+    +----------------------+    +----------------------+
| Sidebar Tab      |--->| PHP OCS Controller   |--->| /api/presidio/*      |
| Right-click menu |    | CloakApiService      |    | /api/encryption-keys |
| (ES Module)      |<---| (Guzzle HTTP)        |<---| /api/presets         |
+------------------+    +----------------------+    +----------------------+
                         API key stored here
                         (IConfig, per-user)

Cloak Files shares the same proxy architecture as Cloak Anonymizer. The API key is stored server-side and never exposed to the browser.

Shared Config Mechanism#

When both apps are installed, Cloak Files uses getEffectiveAppId() to check for a configured API key in the following order:

Cloak Anonymizer config -- checks cloak_anonymizer namespace in IConfig
Cloak Files own config -- falls back to cloak_files namespace

This means you only need to configure the API key once in Cloak Anonymizer.

Troubleshooting#

"Anonymize with Cloak" not showing in right-click menu

Ensure the app is enabled: php occ app:list | grep cloak_files
The file action only appears for supported text-based MIME types
Try reloading the Files page (Ctrl+Shift+R)

Sidebar "Cloak" tab not visible

Open the file details sidebar first (click "Open details")
The tab only appears for text files, not folders or non-text files
Check that the app is enabled

"API key not configured" in the sidebar

If Cloak Anonymizer is installed, configure the API key there
If standalone, configure in Settings > Personal > Security > Cloak Files

File content not loading

Verify the file is a supported text type (check MIME type)
Files over 10 MB are rejected
Check Nextcloud logs for PHP errors

Testing#

The app includes 19 PHPUnit tests covering:

File service operations
API controller methods
Shared config resolution (getEffectiveAppId)
Settings controller

Run tests in Docker:

cd nextcloud_app/docker
MSYS_NO_PATHCONV=1 docker compose exec nextcloud bash -c \
    'cd /opt/cloak_files && php vendor/bin/phpunit --testsuite unit --testdox'

E2E tests (32 Playwright tests):

cd nextcloud_app
python tests/e2e/02_test_cloak_files.py

FAQ#

Do I need both Cloak Anonymizer and Cloak Files? No. Cloak Files works independently for basic sidebar analysis and anonymization. However, the right-click "Anonymize with Cloak" action opens the full Anonymizer UI, so you need both apps for that feature.

What's the difference between the two apps? Cloak Anonymizer is a full-page app with 8 tabs (Dashboard, Anonymize, Image, Structured, Presets, Entities, Keys, Settings). Cloak Files adds two integration points in Nextcloud Files: a sidebar tab and a right-click action. They complement each other.

Can I install Cloak Files without Cloak Anonymizer? Yes. Configure the API key in Cloak Files' own settings (Settings > Personal > Security).

Is Cloak Files free? Yes. Like Cloak Anonymizer, the app is free and open-source (AGPL). API usage is billed through your cloak.business account.