static_encrypt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 634432305d11c47b1ffe73ae7e725f893924f71238981f5365c602927bf3d5b0
+  data.tar.gz: 958774bdc70b2eecfde3bf11f4559472aab1ca08d290d0e71b5f03c511051883
+SHA512:
+  metadata.gz: 2e58edcff5e9d2c1b8c7dd649579541b023443ea1b284f36259317a6d94304b05b66ddaf41a753428571e7dfd1310b3ee85cc9fc1a66d0c8ecd72a203053f296
+  data.tar.gz: da22f8511ee70bbad643845df34b8756e088211c15b389fb58c6bb86c5a0bb4e123f439c0224666e34782fac6730b23b7e741236c569098834dc4a3b7f98e6b3

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Daniël de Vries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,75 @@
+# StaticEncrypt
+
+Password-protect any file as a single, self-contained HTML page. A Ruby take on
+[StatiCrypt](https://github.com/robinmoisson/staticrypt).
+
+The file is encrypted with AES-256-GCM, using a key derived from your password
+with PBKDF2-HMAC-SHA256 (600,000 iterations). The page holds only the
+ciphertext and a small decryptor that runs in the browser with WebCrypto, so you
+can host it anywhere static: GitHub Pages, S3, Netlify.
+
+## Installation
+
+```sh
+gem install static_encrypt
+```
+
+Or, from a checkout:
+
+```sh
+bundle install
+bundle exec rake install
+```
+
+## Usage
+
+Currently, the only way to use this gem is via Ruby: pass the file's contents,
+a password and the file's name to `Page.build`. It returns the
+password-protected page as a string:
+
+```ruby
+require "static_encrypt"
+
+html = StaticEncrypt::Page.build(File.binread("home.html"), "secret", filename: "home.html")
+File.write("home.encrypted.html", html)
+```
+
+Open the page, enter the password, and an HTML file replaces the page; any
+other file (a PDF, an image) is offered as a download under its original name.
+The `filename` is what decides which, its extension sets the download's type.
+
+Optional keyword arguments:
+
+| Argument | Default |
+|---|---|
+| `title:` | `"Protected Page"` |
+| `instructions:` | `"Enter the password to view this content."` |
+| `iterations:` | `600_000` PBKDF2 iterations |
+| `template:` | The built-in page; see below |
+
+To check a page from Ruby, read its payload back and decrypt it. A wrong
+password raises `StaticEncrypt::DecryptionError`:
+
+```ruby
+payload = StaticEncrypt::Page.payload(html)
+StaticEncrypt::Cipher.decrypt(payload, "secret") # => the original bytes
+```
+
+### Custom templates
+
+`template:` takes your own HTML as a string. Start from
+`StaticEncrypt::Page.default_template`, or write one that has:
+
+- `{{script}}` exactly once, where the decryptor is inserted
+- elements with `data-static-encrypt="form"`, `"password"` and `"error"`
+  (and optionally `"submit"`)
+- optionally `{{title}}` and `{{instructions}}`
+
+`Page.build` raises `StaticEncrypt::Error` if any of that is missing.
+
+### Hosting
+
+Browsers only decrypt over **HTTPS** (or on `localhost`, or from a local file).
+Anyone can download the page and guess passwords offline, so use a long,
+random one.
+

data/lib/static_encrypt/cipher.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module StaticEncrypt
+  # AES-256-GCM encryption with a PBKDF2-HMAC-SHA256 derived key, laid out the
+  # way WebCrypto expects it so the browser can decrypt the result.
+  module Cipher
+    DEFAULT_ITERATIONS = 600_000
+    SALT_BYTES = 16
+    IV_BYTES = 12
+    TAG_BYTES = 16
+
+    module_function
+
+    def encrypt(data, password, iterations: DEFAULT_ITERATIONS)
+      raise ArgumentError, "password must not be empty" if password.to_s.empty?
+      raise ArgumentError, "iterations must be a positive integer" unless valid_iterations?(iterations)
+
+      salt = SecureRandom.random_bytes(SALT_BYTES)
+      iv = SecureRandom.random_bytes(IV_BYTES)
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
+      cipher.key = derive_key(password, salt, iterations)
+      cipher.iv = iv
+      cipher.auth_data = ""
+      ciphertext = cipher.update(data) + cipher.final + cipher.auth_tag
+
+      { salt: encode64(salt), iv: encode64(iv), data: encode64(ciphertext), iterations: iterations }
+    end
+
+    def decrypt(payload, password)
+      salt, iv, raw, iterations = parse(payload)
+      ciphertext = raw.byteslice(0...-TAG_BYTES)
+      tag = raw.byteslice(-TAG_BYTES..)
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+      cipher.key = derive_key(password, salt, iterations)
+      cipher.iv = iv
+      cipher.auth_tag = tag
+      cipher.auth_data = ""
+      cipher.update(ciphertext) + cipher.final
+    rescue OpenSSL::Cipher::CipherError
+      raise DecryptionError, "wrong password or corrupted data"
+    end
+
+    def parse(payload)
+      payload = payload.to_h.transform_keys(&:to_sym)
+      salt, iv, raw = payload.fetch_values(:salt, :iv, :data).map { decode64(_1) }
+      iterations = payload.fetch(:iterations)
+
+      raise DecryptionError, "malformed payload: bad iterations" unless valid_iterations?(iterations)
+      raise DecryptionError, "malformed payload: bad salt" if salt.empty?
+      raise DecryptionError, "malformed payload: IV must be #{IV_BYTES} bytes" unless iv.bytesize == IV_BYTES
+      raise DecryptionError, "malformed payload: data too short" if raw.bytesize < TAG_BYTES
+
+      [salt, iv, raw, iterations]
+    rescue KeyError, ArgumentError, TypeError, NoMethodError => e
+      raise DecryptionError, "malformed payload: #{e.message}"
+    end
+
+    def valid_iterations?(iterations) = iterations.is_a?(Integer) && iterations.positive?
+
+    def derive_key(password, salt, iterations)
+      OpenSSL::KDF.pbkdf2_hmac(password, salt: salt, iterations: iterations, length: 32, hash: "sha256")
+    end
+
+    def encode64(bytes) = [bytes].pack("m0")
+    def decode64(string) = string.unpack1("m0")
+  end
+end

data/lib/static_encrypt/decryptor.js

@@ -0,0 +1,120 @@
+// Browser-side decryptor for static_encrypt pages.
+//
+// Page.script wraps this file in a function with `payload` (the encrypted
+// payload) in scope, and injects it at the template's script placeholder. It finds its
+// elements by data attribute, so any template works as long as it has:
+//
+//   [data-static-encrypt="form"]      the form; submitting it decrypts
+//   [data-static-encrypt="password"]  the password input
+//   [data-static-encrypt="error"]     where error messages are shown
+//   [data-static-encrypt="submit"]    optional; disabled while decrypting
+//
+// Messages can be overridden with data attributes on the form:
+// data-wrong-password-message, data-insecure-message, data-decrypting-message,
+// data-decrypted-message.
+//
+// While decrypting, the form has aria-busy="true" and the error element shows
+// the decrypting message, so templates can style that state.
+
+const element = (name) => document.querySelector(`[data-static-encrypt="${name}"]`);
+
+function bytes(b64) {
+  if (Uint8Array.fromBase64) return Uint8Array.fromBase64(b64);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function decrypt(password) {
+  const base = await crypto.subtle.importKey(
+    "raw", new TextEncoder().encode(password), "PBKDF2", false, ["deriveKey"]);
+  const key = await crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt: bytes(payload.salt), iterations: payload.iterations, hash: "SHA-256" },
+    base, { name: "AES-GCM", length: 256 }, false, ["decrypt"]);
+  return new Uint8Array(await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: bytes(payload.iv) }, key, bytes(payload.data)));
+}
+
+function reveal(plain, form) {
+  if (payload.html) {
+    document.open();
+    document.write(new TextDecoder().decode(plain));
+    document.close();
+    return;
+  }
+  const message = document.createElement("p");
+  message.textContent = form.dataset.decryptedMessage || "Decrypted successfully.";
+  const link = document.createElement("a");
+  link.href = URL.createObjectURL(new Blob([plain], { type: payload.mime }));
+  link.download = payload.name;
+  link.textContent = "Download " + payload.name;
+  form.replaceChildren(message, link);
+  link.click();
+}
+
+function init() {
+  const form = element("form");
+  const input = element("password");
+  const error = element("error");
+  if (!form || !input || !error) {
+    console.error('static_encrypt: the template needs [data-static-encrypt="form"], [data-static-encrypt="password"] and [data-static-encrypt="error"].');
+    return;
+  }
+  const submit = element("submit");
+  const messages = {
+    wrongPassword: form.dataset.wrongPasswordMessage || "Wrong password.",
+    insecure: form.dataset.insecureMessage || "This page must be opened over HTTPS to decrypt.",
+    decrypting: form.dataset.decryptingMessage || "Decrypting…"
+  };
+  const insecure = !window.isSecureContext || !window.crypto?.subtle;
+  let busy = false;
+
+  const setBusy = (value) => {
+    busy = value;
+    if (submit) submit.disabled = value;
+    if (value) form.setAttribute("aria-busy", "true");
+    else form.removeAttribute("aria-busy");
+  };
+  const fail = (text) => {
+    error.textContent = text;
+    setBusy(false);
+  };
+
+  if (insecure) {
+    error.textContent = messages.insecure;
+    if (submit) submit.disabled = true;
+  }
+
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    if (insecure || busy) return;
+    setBusy(true);
+    error.textContent = messages.decrypting;
+
+    let plain;
+    try {
+      plain = await decrypt(input.value);
+    } catch (e) {
+      // AES-GCM reports a failed authentication check as OperationError.
+      fail(e.name === "OperationError" ? messages.wrongPassword : "Could not decrypt: " + e.message);
+      return;
+    }
+
+    // The password was right; anything failing from here is about showing the result.
+    try {
+      error.textContent = "";
+      reveal(plain, form);
+      form.removeAttribute("aria-busy");
+    } catch (e) {
+      fail("Decrypted, but could not show the result: " + e.message);
+    }
+  });
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", init);
+} else {
+  init();
+}
+

data/lib/static_encrypt/page.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require "json"
+
+module StaticEncrypt
+  module Page
+    TEMPLATE_PATH = File.expand_path("template.html", __dir__)
+    DECRYPTOR_PATH = File.expand_path("decryptor.js", __dir__)
+
+    DEFAULT_TITLE = "Protected Page"
+    DEFAULT_INSTRUCTIONS = "Enter the password to view this content."
+
+    PLACEHOLDER = /\{\{(\w+)\}\}/
+    PLACEHOLDERS = %w[title instructions script].freeze
+    REQUIRED_ELEMENTS = %w[form password error].freeze
+
+    MIME_TYPES = {
+      ".html" => "text/html", ".htm" => "text/html", ".txt" => "text/plain",
+      ".md" => "text/markdown", ".csv" => "text/csv", ".json" => "application/json",
+      ".pdf" => "application/pdf", ".zip" => "application/zip",
+      ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif", ".svg" => "image/svg+xml", ".webp" => "image/webp",
+      ".mp3" => "audio/mpeg", ".mp4" => "video/mp4"
+    }.freeze
+
+    module_function
+
+    def build(data, password, filename:, template: default_template, title: DEFAULT_TITLE,
+              instructions: DEFAULT_INSTRUCTIONS, iterations: Cipher::DEFAULT_ITERATIONS)
+      validate_template!(template)
+
+      ext = File.extname(filename).downcase
+      payload = Cipher.encrypt(data, password, iterations: iterations).merge(
+        name: filename,
+        mime: MIME_TYPES.fetch(ext, "application/octet-stream"),
+        html: %w[.html .htm].include?(ext)
+      )
+
+      values = {
+        "title" => CGI.escapeHTML(title),
+        "instructions" => CGI.escapeHTML(instructions),
+        "script" => script(payload)
+      }
+      template.gsub(PLACEHOLDER) { values.fetch(Regexp.last_match(1)) }
+    end
+
+    def script(payload)
+      json = JSON.generate(payload).gsub("<", "\\u003c")
+      "<script>\n(() => {\n\"use strict\";\nconst payload = #{json};\n#{decryptor}})();\n</script>"
+    end
+
+    def validate_template!(template)
+      names = template.scan(PLACEHOLDER).flatten
+      unknown = names.uniq - PLACEHOLDERS
+
+      raise Error, "unknown template placeholder(s): #{unknown.map { "{{#{_1}}}" }.join(", ")}" if unknown.any?
+      raise Error, "template must contain {{script}} exactly once" unless names.count("script") == 1
+
+      missing = REQUIRED_ELEMENTS.reject { template.match?(/data-static-encrypt\s*=\s*["']?#{_1}["'\s>]/) }
+
+      raise Error, "template is missing #{missing.map { %(data-static-encrypt="#{_1}") }.join(", ")}" if missing.any?
+
+      template
+    end
+
+    def payload(html)
+      json = html[/const payload = (\{.*?\});$/, 1] or raise Error, "no encrypted payload found"
+      JSON.parse(json, symbolize_names: true)
+    end
+
+    def default_template
+      @default_template ||= File.read(TEMPLATE_PATH, encoding: "UTF-8")
+    end
+
+    def decryptor
+      @decryptor ||= File.read(DECRYPTOR_PATH, encoding: "UTF-8")
+    end
+  end
+end

data/lib/static_encrypt/template.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex">
+  <title>{{title}}</title>
+  <style>
+    :root { --bg: #f4f4f5; --card: #fff; --fg: #18181b; --muted: #71717a;
+            --border: #d4d4d8; --accent: #2563eb; --error: #dc2626; }
+    @media (prefers-color-scheme: dark) {
+      :root { --bg: #09090b; --card: #18181b; --fg: #fafafa; --muted: #a1a1aa;
+              --border: #3f3f46; --accent: #3b82f6; --error: #f87171; }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+           padding: 16px; background: var(--bg); color: var(--fg);
+           font: 16px/1.5 system-ui, -apple-system, sans-serif; }
+    form { width: 100%; max-width: 360px; background: var(--card); padding: 28px;
+           border: 1px solid var(--border); border-radius: 12px; }
+    h1 { font-size: 1.25rem; margin: 0 0 4px; }
+    p { color: var(--muted); margin: 0 0 20px; font-size: .9rem; }
+    a { color: var(--accent); font-weight: 600; }
+    input, button { width: 100%; font: inherit; padding: 10px 12px; border-radius: 8px; }
+    input { border: 1px solid var(--border); background: var(--bg); color: var(--fg); }
+    button { margin-top: 12px; border: 0; background: var(--accent); color: #fff;
+             cursor: pointer; font-weight: 600; }
+    button:disabled { opacity: .6; cursor: not-allowed; }
+    [data-static-encrypt="error"] { color: var(--error); min-height: 1.5em; margin: 8px 0 0; font-size: .875rem; }
+    form[aria-busy="true"] [data-static-encrypt="error"] { color: var(--muted); }
+  </style>
+</head>
+<body>
+  <!--
+    static_encrypt template. See "Custom templates" in the README: the
+    placeholders are title, instructions and script (required, once), and the
+    decryptor needs elements with data-static-encrypt="form", "password" and "error".
+  -->
+  <form data-static-encrypt="form">
+    <h1>{{title}}</h1>
+    <p>{{instructions}}</p>
+    <input data-static-encrypt="password" type="password" placeholder="Password" autocomplete="current-password" autofocus required>
+    <button data-static-encrypt="submit" type="submit">Decrypt</button>
+    <div data-static-encrypt="error" role="alert"></div>
+  </form>
+  {{script}}
+</body>
+</html>
+

data/lib/static_encrypt/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StaticEncrypt
+  VERSION = "0.1.0"
+end

data/lib/static_encrypt.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "static_encrypt/version"
+require_relative "static_encrypt/cipher"
+require_relative "static_encrypt/page"
+
+module StaticEncrypt
+  class Error < StandardError; end
+  class DecryptionError < Error; end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: static_encrypt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniël de Vries
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Encrypts a file with AES-256-GCM (PBKDF2-SHA256 key derivation) and wraps it in a
+  single HTML page that decrypts in the browser with WebCrypto. Host it anywhere.
+email:
+- contact@danieldevries.eu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/static_encrypt.rb
+- lib/static_encrypt/cipher.rb
+- lib/static_encrypt/decryptor.js
+- lib/static_encrypt/page.rb
+- lib/static_encrypt/template.html
+- lib/static_encrypt/version.rb
+homepage: https://github.com/danieldevries/static_encrypt
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/danieldevries/static_encrypt
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Password-protect files as self-contained static HTML pages.
+test_files: []