pagecrypt
Advanced tools
Changelog
5.1.0 - 2021-07-30
Another major UX improvement incoming: Magic links to unlock encrypted pages with a single click!
Also slightly improved browser support for the pagecrypt/core module.
sirv-cli dev dependency since we no longer need HTTPS for local dev.Readme
Easily add client-side password-protection to your Single Page Applications and HTML files.
Inspired by MaxLaumeister/PageCrypt, but rewritten to use native Web Crypto API and greatly improve UX + security. Thanks for sharing an excellent starting point to create this tool!
NOTE: Make sure you are using Node.js v15 or newer.
There are 4 different ways to use pagecrypt:
pagecrypt/coreThe encryptHTML() and generatePassword() functions are using Web Crypto API and will thus be able to run in any ESM compatible environment that supports Web Crypto API.
This allows you to use the same pagecrypt API in any environment where you can run modern JavaScript.
encryptHTML(inputHTML: string, password: string): Promise<string>import { encryptHTML } from 'pagecrypt/core'
const inputHTML = `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
</head>
<body>
Secret
</body>
</html>
`
// Encrypt a HTML string and return an encrypted HTML string.
// Write it to a file or send as an HTTPS response.
const encryptedHTML = await encryptHTML(inputHTML, 'password')
generatePassword(length: number): stringimport { generatePassword, encryptHTML } from 'pagecrypt/core'
// Generate a random password without any external dependencies
const password = generatePassword(64)
const encryptedHTML = await encryptHTML(inputHTML, password)
When working in a Node.js environment, you may prefer the pagecrypt Node.js build. This also includes the encrypt() function to read and write directly from and to the file system.
encrypt(inputFile: string, outputFile: string, password: string): Promise<void>import { encrypt } from 'pagecrypt'
// Encrypt a HTML file and write to the filesystem
await encrypt('index.html', 'encrypted.html', 'password')
NOTE: Importing pagecrypt also gives you access to generatePassword() and encryptHTML() from pagecrypt/core.
import { generatePassword, encryptHTML } from 'pagecrypt'
const password = generatePassword(48)
const encrypted = await encryptHTML(inputHTML, password)
Encrypt a single HTML-file with one command:
npx pagecrypt <src> <dest> [password] [options]
Encrypt using a generated password with given length:
npx pagecrypt <src> <dest> -g <length>
Description
Encrypt the <src> HTML file with [password] and save the result in the <dest> HTML file.
Usage
$ pagecrypt <src> <dest> [password] [options]
Options
-g, --generate-password Generate a random password with given length. Must be a number if used.
-v, --version Displays current version
-h, --help Displays this message
Examples
$ pagecrypt index.html encrypted.html password
$ pagecrypt index.html encrypted.html --generate-password 64
$ pagecrypt index.html encrypted.html -g 64
pagecrypt in your build processUse either the pagecrypt Node.js API or the CLI to automatically encrypt the builds for your single page applications.
npm i -D pagecrypt
package.json:
{
"devDependencies": {
"pagecrypt": "^5.0.0"
},
"scripts": {
"build": "...",
"postbuild": "pagecrypt index.html encrypted.html password"
}
}
pagecryptSince the output is a single HTML file, you can host it anywhere. This lets you bypass the need for server access to use HTTP basic authentication for password protection.
What this means in practice is that pagecrypt enables you to deploy private apps and websites to any static frontend hosting platform, often for free. Great for prototypes and client projects.
To make it easier for your users to access protected pages, you can create a magic link by adding # followed by your password to your deployment URL:
https://<link-to-your-page>#<password>
Then users can simply click the link to load the protected SPA or website - a really smooth UX! Just make sure to keep the link safe by sharing it via E2E-encrypted chats and emails.
#, followed by your password. E.g. https://example.com#passwordhttps:// protocol to keep users safe.Since this magic link feature is using the URI Fragment, it will not be sent across the internet once the user clicks the link. Only the first part before the # leaves the user's computer to fetch the HTML page, and the rest remains in the browser, used for local decryption. Additionally, the fragment is removed from the browser address field when the page loads. However, beware that the password remains as a history entry if you use magic links!
sessionStorage saves the encryption key (which is derived from the password) until the browser is restarted. This is what allows the rapid page reloads during the same session - at the cost of decreasing the security on your local device.pagecrypt only encrypts the contents of a single HTML file, so try to inline as much JS, CSS and other sensitive assets into this HTML file as possible. If you're unable to inline all sensitive assets, you can hide your other assets by placing them on another server, and then only reference the external resources within the pagecrypt protected HTML file instead. Of course, these could in turn be protected or hidden if you need to. If executed correctly, this allows you to completely hide what your webpage or app is about by only deploying a single HTML file to the public web. Neat!Project structure:
/web - Web frontend for public webpage (decrypt-template.html). Built using Vite & Tailwind CSS./src/core.ts - pagecrypt core library./src/index.ts - pagecrypt Node.js library./src/cli.ts - pagecrypt CLI./test - simple testing setup./scripts - local scripts for development tasks.npm install in project root.npm test will run basic tests for JS API and CLI. See the passwords used in your terminal. Verify test results by opening the test/out-*.html files in your browser and entering the password matching the file.
To test how pagecrypt/core works with encryption in browser environments, run cd test && npm run test:browser-core. Then download the encrypted sample file and use the "actual" password that's printed to the screen to verify it works. The generated password just shows that the password generation works.
Welcome to submit issues and pull requests!
FAQs
Easily add client-side password-protection to your Single Page Applications and HTML files.
We found that pagecrypt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
Application Security
New SEC disclosure rules aim to enforce timely cyber incident reporting, but fear of job loss and inadequate resources lead to significant underreporting.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).