Cloud Stash Plugin

The Cloud Stash Plugin is an extension for Grav CMS. Stash your users' form data in a secure cloud repository.

You might want this plugin if your users submit sensitive information you don't want to store on your web server. If you use specific cloud storage services, you can send your users' data there using credentials that are limited to dropping items and don't allow reads. In so doing, if your web server is compromised, attackers will not be able to access your users' sensitive data.

This could be handy for:

• confidential surveys;
• application and registration forms with sensitive info (e.g. medical history, income details);
• secret ballots.

Installation

Installing the Cloud Stash plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.

Dependencies

This plugin requires the Form plugin to provide anything useful.

The Snappygrav plugin (>= v1.9.1) is also listed as a dependency, though you won't strictly need this if you don't need to stash PDF documents.

If you use this plugin without producing PDFs (Snappygrav), you could install it manually according to the instructions below.

Note that Snappygrav requires you to either install or make sure you have a PDF creation library available on your server.

GPM Installation (Preferred)

To install the plugin via the GPM, through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:

bin/gpm install cloud-stash

This will install the Cloud Stash plugin into your /user/plugins-directory within Grav. Its files can be found under /your/site/grav/user/plugins/cloud-stash.

Manual Installation

To install the plugin manually, download the zip-version of this repository and unzip it under /your/site/grav/user/plugins. Then rename the folder to cloud-stash. You can find these files on GitHub or via GetGrav.org.

You should now have all the plugin files under

/your/site/grav/user/plugins/cloud-stash

NOTE: This plugin is a modular component for Grav which may require other plugins to operate, please see its blueprints.yaml-file on GitHub.

Admin Plugin

If you use the Admin Plugin, you can install the plugin directly by browsing the Plugins-menu and clicking on the Add button.

Configuration

Before configuring this plugin, you should copy the user/plugins/cloud-stash/cloud-stash.yaml to user/config/plugins/cloud-stash.yaml and only edit that copy.

Here is the default configuration and an explanation of available options:

enabled: true
stashes:
  AWS:
    region: ''                  # AWS BUCKET REGION
    key: ''                     # AWS KEY
    secret: ''                  # AWS PASSWORD
    # domain:                   # e.g. 'backblazeb2.com' for Backblaze B2 (see https://www.backblaze.com/b2/docs/s3_compatible_api.html and below)
                                # e.g. 'linodeobjects.com' for Linode Object Storage stashes
    # defaults:
    #  target: 'fave-bucket'

• enabled toggles the plugin on and off
• stashes holds information about the cloud storage provider services you have set up and want to make available. Presently only some AWS S3 API-compatible providers are supported.
• domain for some S3-compatible API providers like Minio servers, Backblaze B2 Cloud Storage, and Linode Object Storage, you need to specify an endpoint domain for concatenating to the region hostname so that your S3-compatible API calls use "path-style endpoints" and the API calls work correctly.
• defaults.target the default bucket to write to if one is not explicitly specified as a bucket parameter. This allows different bucket targets per environment without needing to vary the form's YAML, so .. useful!

Note that if you use the Admin Plugin, a file with your configuration named cloud-stash.yaml will be saved in the user/config/plugins/-folder once the configuration is saved in the Admin.

Usage

At present the plugin only supports Amazon Web Services S3 buckets and S3-compatible API service buckets/objects, but has been developed to facilitate adding support for other service providers.

The plugin defines two new form actions for Grav forms. Place these as required under the process form YAML property.

• stash saves a form data file, and optionally file field attachments uploaded through the form, to a remote storage location that you specify.
• stash_pdf saves a formatted PDF file based on form input, and optionally file fields uploaded through the form, to a remote storage location that you specify.

If you use both of these actions, you probably only want to specify that file fields be stashed in one of those actions. If you specify any field twice, its attachment will be overwritten. This is mostly harmless except for the extra traffic and time taken.

stash action

The parameters fileprefix, filepostfix, dateformat, dateraw, filename, extension, and body are available and function identically to the form plugin's bundled 'save' action parameters.

Just like the 'save' action, if you omit the body parameter, your output will be formatted using the 'forms/data.html.twig' template from your theme, Form plugin, or other location in your Twig path.

stash specifies the stash name as configured under stashes in this plugin's configuration.

provider deprecated for stash, will be interpreted as stash if provided in lieu of stash. It's ignored if you provide it as well.

bucket is S3-specific and may be deprecated for a more service-agnostic term in the near future. It specifies the name of the S3-compatible bucket into which you want to stash your form data.

add_uploads is a YAML list of file field names from the form, which indicates that you would like those files to be uploaded to the remote stash as well.

operation is not supported and is ignored. Documents/objects are always created.

Example

    …
    process:
        …
        - stash:
            filename: "{{ 'questionnaire-' ~ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['respondent-name']|e|split(' ')|last|lower ~ '.yaml' }}"
            foldername: "{{ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['respondent-name']|e|split(' ')|last|lower }}"
            extension: yaml
            body: "{% include 'forms/data.txt.twig' %}"
            stash: AWS # old property 'provider' still supported, don't use it though
            bucket: MY.BUCKET.NAME
            add_uploads:
                - attachments
                - supporting_documents
        …

stash_pdf action

As per the stash action except that extension will be ignored and set to ".pdf".

Example

    …
    process:
        …
        - stash_pdf:
            filename: "{{ 'application-' ~ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['applicant-name']|e|split(' ')|last|lower ~ '.pdf' }}"
            foldername: "{{ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['applicant-name']|e|split(' ')|last|lower }}"
            body: "{% include 'forms/application-print.html.twig' %}"
            stash: B2 # old property 'provider' still supported, don't use it though
            bucket: MY.BUCKET.NAME
        …

Credits

This plugin makes use of a bunch of wonderful open source software and requires the Snappygrav plugin to produce PDFs for uploading/stashing.

Many thanks to Matt Marsh (@marshmn) and @robertorubioguardia for S3 advice and mentoring.

TODO: more credits

To Do

The most important TODOs have been added as repository issues for now. FIXME

Dropbox support is not a priority because it doesn't support write-only permissions, despite its name. It may, however, have value for its ability to provide seamless mount points to the user's local file system.