This article describes the security model and developer extension points in Nelx Secure Document Storage v1.3.18. It is intended for site administrators, developers and teams building workflows around secured WordPress attachments.
What the Plugin Protects #
The plugin moves supported attachments into protected local storage, records the file as secured, retains the original filename as metadata and serves document bytes through a checked PHP endpoint.
It is not an encryption-at-rest product, cloud-storage service or public link-sharing system. It also does not implement document versioning or audit logs for every access attempt.
File Delivery Checks #
Each View/Download request validates:
- The action (
viewordownload) and numeric attachment ID. - A file-specific WordPress nonce.
- A logged-in WordPress user.
- The attachment’s
_nelxsdst_secure_filemarker. - The attachment’s actual, readable local file and its placement within recognized secure storage.
- The current user’s permission to access that attachment.
Authorized bytes are streamed in bounded 1 MiB chunks, with private/no-store and nosniff response headers. Only PDF, JPEG, PNG, GIF, WebP and plain text are eligible for inline viewing; other MIME types are delivered as downloads. Browser range requests and server-offloaded delivery are not provided in this version.
A link’s nonce is not a substitute for authorization. Do not treat these URLs as permanent public sharing links.
Normal Access Decision #
For an ordinary, unscoped secured file, authorization can come from a user with manage_options, nelxsdst_access_all_secure_files, recorded secure-file ownership, a configured global role or an applicable JetFormBuilder form-level role grant.
The backend Files list applies an additional own-files restriction for users granted only the own-files library role. File delivery and backend-list visibility therefore serve different purposes.
Application-Scoped Access in v1.3.14 #
The v1.3.18 package adds an opt-in mechanism for applications that require permission checks tied to a specific business record rather than broad WordPress roles.
If an attachment has a nonempty _nelxsdst_policy_context meta value, the normal administrator, owner, global and form-role grants no longer decide access. The plugin calls:
apply_filters(
'nelxsdst_scoped_file_access',
null,
$attachment_id,
$user_id,
$scoped_context
);Only an explicit boolean true grants access. false, null and other results are denied. If the relevant integration is disabled or does not recognize the context, access fails closed.
For example, an application may use loan_application as a context label. Its integration must independently validate the document-to-record relationship and the requesting user’s authorization for that particular record. Do not return true based on a role name alone. The core plugin does not supply a default business-specific rule.
This extension affects secured files carrying the scoped metadata only. Files without _nelxsdst_policy_context retain the existing access model. Administrators should test scoped files separately; assigning broad Secure Files roles will not bypass that policy.
Important Attachment Metadata #
| Meta key | Purpose |
|---|---|
_nelxsdst_secure_file | Marks an attachment as secured |
_nelxsdst_secure_owner | Recorded owner WordPress user ID, if any |
_nelxsdst_original_filename | Name displayed to authorized users |
_nelxsdst_secure_path | Recorded secure relative path |
_nelxsdst_file_size | Stored file-size metadata |
_nelxsdst_source | manual, jetformbuilder, api or legacy |
_nelxsdst_form_id | Associated JetFormBuilder form ID where available |
_nelxsdst_policy_context | Optional context that activates the scoped-access filter |
Existing files may have older metadata arrangements; the access layer retains compatibility paths for legacy form association.
Storage Configuration #
The primary configuration constant is:
define( 'NELXSDST_STORAGE_PATH', '/absolute/private/nelx-secure-files' );It can alternatively be set through the early-loading nelxsdst_storage_path filter. Use an absolute local path, not a URL or remote filesystem endpoint.
Changing the path affects new files. Existing attachments retain their recorded file paths, and the original saved storage root remains recognized. Do not remove or expose the old root while documents are stored there.
Publicly Served Uploads Directories #
Apache/LiteSpeed installations must honor the generated .htaccess restrictions. Nginx does not interpret .htaccess: configure an equivalent server-level deny rule for the actual secure uploads URL path, including any custom uploads base or aliases.
For security-sensitive deployments, private storage outside the document root is preferable. Confirm direct URL denial with an unauthenticated request; a writable-directory check alone is not sufficient.
PHP APIs for Integrations #
The shared service is:
NELXSDST_Storage_Service::ingest_attachment( $attachment_id, $context );This secures an existing WordPress attachment and returns true or WP_Error. It is not a public upload endpoint. Callers must independently verify their request’s nonce, identity, field permission, file restrictions and upload ownership before invoking it.
Context values may include source, owner, original_name and form_id where applicable. Do not bypass the plugin’s storage-root and secure-path validation.
Other relevant methods include:
NELXSDST_SecureStorage::is_file_secured( $attachment_id )NELXSDST_File_Access::user_can_access_file( $attachment_id, $user_id )NELXSDST_File_Access::get_secure_file_url( $attachment_id, 'view' )NELXSDST_File_Access::get_secure_file_url( $attachment_id, 'download' )
When a trusted JetFormBuilder live-upload integration is involved, prepare_live_upload_dir() and finalize_live_attachment() are available on the storage instance. Their use still depends on the separate verified JetFormBuilder request boundary; do not expose them as unauthenticated public actions.
Shortcode and Admin Interfaces #
Registered shortcodes are nelx_secure_file and nelx_secure_files. Saved styling/configuration presets are stored under the WordPress option nelxsdst_shortcode_presets.
Backend entry uses nelxsdst_access_secure_files, with nelxsdst_access_all_secure_files for broad ordinary-file access. The admin file table uses locally bundled DataTables 2.3.4. Secure attachments are filtered from standard media selection and protected against raw media URL exposure.
Recommended Security Checks Before Launch #
- Verify the web server denies direct access to actual storage paths.
- Test authorized and unauthorized users against the same file.
- Test own-files staff accounts against documents owned by another user.
- Check global and JetFormBuilder form-level role grants.
- Test scoped-policy files with the integration enabled, disabled, and returning denial.
- Confirm a guest uploader does not gain an anonymous file-viewing route.
- Exclude private-document pages from shared caching.
- Back up secured file directories and their corresponding WordPress attachment/meta records together.
Version Note #
This documentation covers the 1.3.14 and newer plugin code, including the opt-in scoped-access extension. Check the installed plugin version before applying the developer guidance to an older installation.
For operational issues, see Troubleshooting and Frequently Asked Questions

