freshjots 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54b9c5dc0f9e2eef0978dc53579737fe6cf52fefee6b4105c9a8903761c7817b
-  data.tar.gz: 2c40157c50f2ad882ede4486762b90f0cb35c715922e66c4533715100aafdddc
+  metadata.gz: 5a9a2097c87005bc6e9b43c35881949e54bce2871962789f463ed347b4e2e415
+  data.tar.gz: 18f981d7b062f4e683b0c4bb4331f6be9442e94cad3f4067dea8847ed9d3893e
 SHA512:
-  metadata.gz: bf52b3c3da728a65071d7bcd6cd5c4cac197c17f293747ff870d7299365be80b1007c0787417e0fc2430decd389956ca518a2c4950f53c8b78364dc2f772fad7
-  data.tar.gz: 442c1eccc0d157c7c0cb48b304ddc75ac6c23099f1723ad1623c3dbcf658887ff9f7e9a82412e47e4a90f2f47914d9104a25ce4677e4dfdf2168267943909bb1
+  metadata.gz: 00b9d55134d2826c0aa1515277907e31bcd1cb9b0df62918e194ca4b7f7e2542008fb3236b5503cb815ebde47702e4bac1e094a6ba3d2a5ac025ebb5ebf89171
+  data.tar.gz: f5f7dbcc724409cdb3b969972e0c5ff455abc715f3fc0da6650eaf1b6c654693ebd3a69c93c8f2f67aff021b529c41b37f90b506f3ead3d1e059737bfc4c4b85

data/README.md

@@ -50,7 +50,35 @@ client.delete("old-note")
 client.folders.each { |f| puts "#{f[:id]}\t#{f[:name]}" }
 ```
 
-Client methods: `notes(sort:, folder_id:, limit:, offset:)`, `note(filename)`, `note_by_id(id)`, `create(title:, body:)`, `append(filename, text)`, `delete(id_or_filename)`, `move(id_or_filename, folder:)`, and `folders`. `note`/`note_by_id`/`create` return the note hash directly (no `{ note: … }` wrapper); `notes` and `folders` return arrays. For `notes`, `sort` is `created|updated|appended` and `folder_id` may be a folder id or `"none"` (un-foldered only).
+Client methods: `notes(sort:, folder_id:, limit:, offset:)`, `note(filename)`, `note_by_id(id)`, `create(title:, body:, client_encrypted:)`, `append(filename, text, client_encrypted:)`, `delete(id_or_filename)`, `move(id_or_filename, folder:)`, and `folders`. Client-side crypto: `Freshjots.encrypt(text, passphrase)` / `Freshjots.decrypt(token, passphrase)` (see [Encryption](#encryption)). `note`/`note_by_id`/`create` return the note hash directly (no `{ note: … }` wrapper); `notes` and `folders` return arrays. For `notes`, `sort` is `created|updated|appended` and `folder_id` may be a folder id or `"none"` (un-foldered only).
+
+## Encryption
+
+Keep notes the server can't read: encrypt locally with your own passphrase,
+store the ciphertext, decrypt locally on read. Built in on Ruby's stdlib
+`openssl` (no gem dependencies), and interoperable with the JS and Python
+clients.
+
+```ruby
+require "freshjots"
+
+client = Freshjots::Client.new
+pw = ENV.fetch("FRESHJOTS_PASSPHRASE")
+
+# Store an encrypted note: encrypt the body, flag it client_encrypted.
+client.create(title: "Recovery codes", body: Freshjots.encrypt("1234-5678", pw), client_encrypted: true)
+
+# Read it back and decrypt locally.
+puts Freshjots.decrypt(client.note("recovery-codes")[:plain_body], pw)
+```
+
+The format is `fj1` (AES-256-CBC + HMAC-SHA256, PBKDF2-HMAC-SHA256), interoperable
+with the JS, Python, MCP, and shell (`brew`) clients. You hold the only key —
+Fresh Jots never receives it and **cannot recover the note if you lose it**, so
+back the passphrase up somewhere safe. Encryption is per-note and personal-only
+(not team notes); the title and metadata stay in the clear, so keep secrets out
+of the title. `Freshjots.decrypt` raises `Freshjots::EncryptionError` on a wrong
+passphrase. See <https://freshjots.com/encrypted-notes>.
 
 ## Errors
 

data/lib/freshjots/crypto.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "securerandom"
+
+# Client-side encryption for Fresh Jots notes — format "fj1".
+#
+# Encrypt locally with your own passphrase; the server stores only the
+# ciphertext and can never read it. Wire format:
+#
+#   "fj1:" + base64( salt[16] | iv[16] | ciphertext | mac[32] )
+#
+# A single PBKDF2-HMAC-SHA256 pass (210_000 iterations) derives 64 bytes from
+# the passphrase and salt: the first 32 are the AES-256-CBC key, the last 32 the
+# HMAC-SHA256 key. The note is AES-256-CBC encrypted, then authenticated
+# encrypt-then-MAC over iv|ciphertext; decryption verifies the MAC before
+# decrypting. The output is a single line (base64 carries no newlines), so it
+# survives the server's newline append separator. The format is identical
+# across the Fresh Jots JS, Python, Ruby, and shell clients: a note encrypted
+# by one decrypts with the others. (CBC+HMAC, not GCM, because it is the one
+# authenticated construction every client — including the bash CLI, whose
+# openssl refuses AEAD — can implement identically.) Uses only Ruby's stdlib
+# openssl (no gem deps).
+module Freshjots
+  class EncryptionError < StandardError; end
+
+  FJ_PREFIX     = "fj1:"
+  FJ_ITERATIONS = 210_000
+  FJ_SALT_LEN   = 16
+  FJ_IV_LEN     = 16
+  FJ_MAC_LEN    = 32
+
+  # True if the text carries the Fresh Jots ciphertext prefix ("fj1:"). A
+  # declaration of shape, not a guarantee it decrypts.
+  def self.encrypted?(text)
+    text.is_a?(String) && text.start_with?(FJ_PREFIX)
+  end
+
+  # Encrypt a string with a passphrase; returns an "fj1:" token.
+  def self.encrypt(plaintext, passphrase)
+    raise ArgumentError, "encrypt requires a passphrase" if passphrase.nil? || passphrase.empty?
+
+    salt = SecureRandom.random_bytes(FJ_SALT_LEN)
+    iv   = SecureRandom.random_bytes(FJ_IV_LEN)
+    enc_key, mac_key = fj_derive_keys(passphrase, salt)
+    cipher = OpenSSL::Cipher.new("aes-256-cbc")
+    cipher.encrypt
+    cipher.key = enc_key
+    cipher.iv  = iv
+    ciphertext = cipher.update(plaintext.to_s) + cipher.final
+    mac = OpenSSL::HMAC.digest("SHA256", mac_key, iv + ciphertext)
+    FJ_PREFIX + Base64.strict_encode64(salt + iv + ciphertext + mac)
+  end
+
+  # Decrypt an "fj1:" token back to its plaintext. Raises EncryptionError on a
+  # malformed token, a wrong passphrase, or tampering.
+  def self.decrypt(token, passphrase)
+    raise ArgumentError, "decrypt requires a passphrase" if passphrase.nil? || passphrase.empty?
+    raise EncryptionError, "not a Fresh Jots ciphertext (missing 'fj1:' prefix)" unless encrypted?(token)
+
+    blob =
+      begin
+        Base64.strict_decode64(token[FJ_PREFIX.length..])
+      rescue ArgumentError
+        raise EncryptionError, "ciphertext is not valid base64"
+      end
+    if blob.bytesize < FJ_SALT_LEN + FJ_IV_LEN + FJ_MAC_LEN + 16
+      raise EncryptionError, "ciphertext is truncated or corrupted"
+    end
+
+    salt   = blob.byteslice(0, FJ_SALT_LEN)
+    iv     = blob.byteslice(FJ_SALT_LEN, FJ_IV_LEN)
+    mac    = blob.byteslice(blob.bytesize - FJ_MAC_LEN, FJ_MAC_LEN)
+    ct_len = blob.bytesize - FJ_SALT_LEN - FJ_IV_LEN - FJ_MAC_LEN
+    ct     = blob.byteslice(FJ_SALT_LEN + FJ_IV_LEN, ct_len)
+
+    enc_key, mac_key = fj_derive_keys(passphrase, salt)
+    expected = OpenSSL::HMAC.digest("SHA256", mac_key, iv + ct)
+    unless mac.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(mac, expected)
+      raise EncryptionError, "decryption failed — wrong passphrase or corrupted ciphertext"
+    end
+
+    cipher = OpenSSL::Cipher.new("aes-256-cbc")
+    cipher.decrypt
+    cipher.key = enc_key
+    cipher.iv  = iv
+    begin
+      (cipher.update(ct) + cipher.final).force_encoding("UTF-8")
+    rescue OpenSSL::Cipher::CipherError
+      raise EncryptionError, "decryption failed — wrong passphrase or corrupted ciphertext"
+    end
+  end
+
+  # PBKDF2-HMAC-SHA256 -> 64 bytes split into (AES-256-CBC key, HMAC-SHA256 key).
+  def self.fj_derive_keys(passphrase, salt)
+    dk = OpenSSL::KDF.pbkdf2_hmac(
+      passphrase.to_s,
+      salt: salt, iterations: FJ_ITERATIONS, length: 64, hash: "sha256"
+    )
+    [dk.byteslice(0, 32), dk.byteslice(32, 32)]
+  end
+  private_class_method :fj_derive_keys
+end

data/lib/freshjots/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Freshjots
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

data/lib/freshjots.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "uri"
 
 require_relative "freshjots/version"
+require_relative "freshjots/crypto"
 
 # Tiny client for the Fresh Jots API (https://freshjots.com/docs).
 #
@@ -71,18 +72,27 @@ module Freshjots
     # (the by-filename endpoint creates it with that exact name on first
     # call). Returns the created note hash (top level); read [:filename]
     # for the server-derived stream name.
-    def create(title:, body: "")
+    # Pass client_encrypted: true to mark the note as a client-encrypted note
+    # — body is opaque ciphertext you produced with Freshjots.encrypt; the
+    # server stores it verbatim and never reads it. Personal accounts only.
+    def create(title:, body: "", client_encrypted: false)
       if title.nil? || title.to_s.empty?
         raise ArgumentError,
               "create requires a title — the API derives the filename from it. " \
               "For a note addressable by an exact filename, use append."
       end
-      payload = { note: { title: title, plain_body: body, format: "plain" } }
-      request(:post, "/notes", payload)
+      note = { title: title, plain_body: body, format: "plain" }
+      note[:client_encrypted] = true if client_encrypted
+      request(:post, "/notes", { note: note })
     end
 
-    def append(filename, text)
-      request(:post, "/notes/by-filename/#{escape(filename)}/append", { text: text })
+    # On first-touch creation, pass client_encrypted: true to open the stream
+    # as a client-encrypted note (send one ciphertext line per append).
+    # Ignored once the note exists.
+    def append(filename, text, client_encrypted: false)
+      body = { text: text }
+      body[:client_encrypted] = true if client_encrypted
+      request(:post, "/notes/by-filename/#{escape(filename)}/append", body)
       true
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: freshjots
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Goran Arsov
@@ -20,6 +20,7 @@ files:
 - LICENSE
 - README.md
 - lib/freshjots.rb
+- lib/freshjots/crypto.rb
 - lib/freshjots/version.rb
 homepage: https://github.com/Goran-Arsov/freshjots-ruby
 licenses: