StatiCrypt

StatiCrypt is a tool used to safely encrypt and password-protect the content of public static HTML files. The decryption happens entirely in-browser using AES-256 and WebCrypto, meaning no back-end server is required. This makes it suitable for hosting on static platforms like Netlify or GitHub Pages.

Users can encrypt files in two ways:

1. Online: Use the browser-based client-side tool at robinmoisson.github.io/staticrypt.
2. CLI: Use the Command Line Interface for terminal or automated build processes.

StatiCrypt 3.x introduces several improvements including strong default security via WebCrypto and a simplified password_template.

Key Compatibility Notes:

• HTTPS Requirement: 3.x uses WebCrypto exclusively, which requires the files to be served over HTTPS or localhost. If you must serve files over plain HTTP, you must remain on version 2.x.
• Node.js Requirement: The minimum required Node.js version is 16. For older Node.js versions, stay on 2.x to use the cryptoJS engine.
• Backward Compatibility: Auto-decrypt "share" links and "remember-me" functionality created with 2.x remain compatible with 3.x.

If you use a custom password template, you must update it for 3.x compatibility. The new template logic is simpler and uses a different variable injection syntax.

Steps to update:

1. Obtain the new logic from lib/password_template.html and replace the JavaScript portion of your custom template.
2. Update your template variables. The new syntax uses /*[|variable|]*/0 instead of the old {variable} syntax.

Variable Mapping:

You can customize the look and feel of the password prompt by providing a custom HTML template.

1. Copy lib/password_template.html to your desired location.
2. Modify the HTML to your preference.
3. Important: Do not break the encryption JavaScript. StatiCrypt uses a specific variable format: /*[|variable|]*/0. Ensure you keep the 0 at the end of these tokens to avoid conflicts with other templating engines and to maintain valid JS syntax.
4. Use the -t flag to point to your template during encryption.

StatiCrypt currently supports only one password per page. To support multiple users with individual passwords (and the ability to invalidate them separately), use a script to encrypt files into different output directories for each user.

Example workflow:

1. Encrypt test.html with a specific user's password into a dedicated folder: staticrypt test.html -p <user-password> -d <user-folder>.
2. Provide the user with the link to their specific folder: https://example.com/<user-folder>/test.html.

staticrypt test.html -p <john-password> -d john

You can install StatiCrypt as a CLI tool using npm. You can either install it locally and run it via npx or install it globally to use the staticrypt command directly from your terminal.

# Local installation
npm install staticrypt
npx staticrypt ...

# Global installation
npm install -g staticrypt
staticrypt ...

To ensure 'Remember-me' or shareable links work across different deployments or multiple pages, the salt must remain constant. You can pin the salt by:

1. Committing the generated .staticrypt.json file to your repository.
2. Generating a random salt and saving it locally with staticrypt --salt.
3. Hardcoding a 32-character hexadecimal salt directly in your command.

StatiCrypt uses a configuration file (.staticrypt.json) to store the salt used for the 'Remember me' feature. This ensures the salt remains consistent across different encryption runs, preventing users from being logged out when a page is re-encrypted.

• Salt Priority: StatiCrypt looks for a salt in this order: the --salt flag, then the config file, and finally generates a random one if none is found.
• Disabling Config: To prevent StatiCrypt from creating or using a config file, use the --config false flag.
• CI/CD Usage: If encrypting as part of a CI/CD pipeline, you can commit the .staticrypt.json file so the build server has access to the consistent salt.

The 'Remember me' feature allows users to stay logged in by storing a salted and hashed version of their password in the browser's localStorage.

• Enable/Disable: The checkbox is included by default. Use --remember false to remove it.
• Expiration: By default, the stored password does not expire. To set an expiration, provide a number of days using --remember NUMBER_OF_DAYS.
• Scope: This works across multiple pages if they are hosted on the same domain, as they share the same localStorage.
• Logging out: Users can manually clear their session by appending staticrypt_logout to the URL fragment (e.g., https://mysite.com#staticrypt_logout).