freshjots 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54b9c5dc0f9e2eef0978dc53579737fe6cf52fefee6b4105c9a8903761c7817b
-  data.tar.gz: 2c40157c50f2ad882ede4486762b90f0cb35c715922e66c4533715100aafdddc
+  metadata.gz: 3916dec8cefe696476c18a0a28aba36a1657721082098eef1929129c05355b84
+  data.tar.gz: 94b852d213f92017d897fe309efd21f9ecf60c6d398e0cbfe6c37af0f11219b0
 SHA512:
-  metadata.gz: bf52b3c3da728a65071d7bcd6cd5c4cac197c17f293747ff870d7299365be80b1007c0787417e0fc2430decd389956ca518a2c4950f53c8b78364dc2f772fad7
-  data.tar.gz: 442c1eccc0d157c7c0cb48b304ddc75ac6c23099f1723ad1623c3dbcf658887ff9f7e9a82412e47e4a90f2f47914d9104a25ce4677e4dfdf2168267943909bb1
+  metadata.gz: 8c650cb3dfdb4ff2c3d4680652e9fa8ec82cfd2fa5f6605fe9e33a3f67b3b6149d46ac5b3f6aada3cb2b3a7c4c8e77d2e4ebf98c122a5957439ce2205001aa9b
+  data.tar.gz: 1ee7ec3cace2bf20ce328f27d9ffb1ed91348eabb5fc3bf1354a9c21f09cd06707d22ca8f9beeb8dfc42b23a39bf8c873d19c0d7bc48af8089f149d659ede7e9

data/README.md

@@ -44,13 +44,53 @@ end
 created = client.create(title: "Research 2026 Q2", body: "Initial outline.")
 puts created[:filename] # server-derived stream name
 
-# Organize: move into a folder (by id or name), delete (by id or filename), list folders.
+# Update a note's fields (only the keys you pass change). By id or by filename:
+client.update(42, title: "Q2 research", body: "Revised outline.")
+client.set("cron-jobs-prod", folder: "Ops", deadline: 26)   # metadata only, no body needed
+
+# Create many notes in one atomic batch (up to 50 — all land or none do).
+client.bulk([{ title: "a", plain_body: "1" }, { title: "b", plain_body: "2" }])
+
+# Organize: move into a folder (by id or name), delete (by id or filename).
 client.move("cron-jobs-prod", folder: "Ops")
 client.delete("old-note")
+
+# Folders: list, read one, create, rename, delete (its notes survive, un-foldered).
 client.folders.each { |f| puts "#{f[:id]}\t#{f[:name]}" }
+ops = client.create_folder("Ops")
+client.rename_folder(ops[:id], "Operations")
+client.delete_folder(ops[:id])
+```
+
+Client methods: `notes(sort:, folder_id:, limit:, offset:)`, `note(filename)`, `note_by_id(id)`, `create(title:, body:, client_encrypted:)`, `append(filename, text, client_encrypted:)`, `update(id, **fields)`, `set(filename, **fields)`, `bulk(notes)`, `delete(id_or_filename)`, `move(id_or_filename, folder:)`, `folders`, `folder(id)`, `create_folder(name)`, `rename_folder(id, name)`, and `delete_folder(id)`. Client-side crypto: `Freshjots.encrypt(text, passphrase)` / `Freshjots.decrypt(token, passphrase)` (see [Encryption](#encryption)). `note`/`note_by_id`/`create`/`update`/`set` and the single-folder methods return the hash directly (no `{ note: … }` / `{ folder: … }` wrapper); `notes` and `folders` return arrays, and `bulk` returns `{ created: [...] }`. For `update`/`set`, the fields are `title:`, `body:`, `folder:` (id or name — `root: true` un-folders), `deadline:`, `alert_email:`, `webhook_url:`, `webhook_secret:`; changing `title:` rewrites the body as a unit, so pass `body:` too. 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)
 ```
 
-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).
+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.2.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).
 #
@@ -33,6 +34,11 @@ module Freshjots
 
   class Client
     DEFAULT_BASE_URL = "https://freshjots.com/api/v1"
+    BULK_MAX = 50
+    # Friendly field names accepted by #update / #set, mapped to the API's
+    # note keys in #note_fields. append_only / format are intentionally
+    # absent — the API does not update them.
+    UPDATABLE_FIELDS = %i[title body folder root deadline alert_email webhook_url webhook_secret].freeze
 
     def initialize(token: ENV["FRESHJOTS_TOKEN"], base_url: DEFAULT_BASE_URL)
       raise ArgumentError, "FRESHJOTS_TOKEN missing — pass token: or set the env var" if token.nil? || token.empty?
@@ -71,24 +77,61 @@ 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
 
+    # Update a note by id. Pass any of: title:, body:, folder:, root: true,
+    # deadline:, alert_email:, webhook_url:, webhook_secret: — only the keys
+    # you pass are changed, so an unmentioned field is never clobbered. A
+    # content change (title/body) rewrites the body as a unit, so a title
+    # change needs body: too (the API requires plain_body). append_only and
+    # format are not updatable. Returns the updated note hash (top level).
+    def update(id, **fields)
+      request(:patch, "/notes/#{escape(id)}", { note: note_fields(fields) })
+    end
+
+    # Update a note addressed by its exact filename / stream name. Same
+    # fields as #update.
+    def set(filename, **fields)
+      request(:patch, "/notes/by-filename/#{escape(filename)}", { note: note_fields(fields) })
+    end
+
+    # Create up to 50 notes in one atomic batch (all land or none do).
+    # `notes` is an array of note hashes ({ title:, plain_body:,
+    # format: "plain" }). Returns the response ({ created: [...] }).
+    def bulk(notes)
+      items = Array(notes)
+      raise ArgumentError, "bulk requires at least one note" if items.empty?
+      raise ArgumentError, "bulk accepts at most #{BULK_MAX} notes (got #{items.size})" if items.size > BULK_MAX
+
+      request(:post, "/notes/bulk", { notes: items })
+    end
+
     # Delete a note. Accepts a numeric id or a filename (resolved to its
-    # id via the by-filename lookup). Locked (append-only) notes are
-    # refused by the API with note_locked. Returns true on success.
+    # id via the by-filename lookup). Works on any note, including locked
+    # (append-only) ones — the lock freezes content, not deletability.
+    # Returns true on success.
     def delete(id_or_filename)
       request(:delete, "/notes/#{resolve_note_id(id_or_filename)}")
       true
@@ -107,6 +150,28 @@ module Freshjots
       request(:get, "/folders")[:folders]
     end
 
+    # Fetch one folder by id (GET /folders/:id) — top-level serializer.
+    def folder(id)
+      request(:get, "/folders/#{escape(id)}")
+    end
+
+    # Create a folder. Returns the created folder hash (top level).
+    def create_folder(name)
+      request(:post, "/folders", { folder: { name: name } })
+    end
+
+    # Rename a folder. Returns the updated folder hash.
+    def rename_folder(id, name)
+      request(:patch, "/folders/#{escape(id)}", { folder: { name: name } })
+    end
+
+    # Delete a folder by id. Its notes survive — they just become
+    # un-foldered. Returns true.
+    def delete_folder(id)
+      request(:delete, "/folders/#{escape(id)}")
+      true
+    end
+
     private
 
     # A note reference is either a numeric id (used as-is) or a
@@ -130,6 +195,42 @@ module Freshjots
       matches.first[:id]
     end
 
+    # Map the friendly #update / #set keyword fields to the API's note keys,
+    # sending only what the caller passed. A title change rewrites the body
+    # as a unit (the API requires plain_body), so a title-only change is
+    # refused here — mirrors the CLI. Unknown fields and an empty change are
+    # errors. `folder:` accepts an id or a name (resolved via /folders);
+    # `root: true` un-folders the note.
+    def note_fields(fields)
+      unknown = fields.keys - UPDATABLE_FIELDS
+      unless unknown.empty?
+        raise ArgumentError,
+              "unknown update field(s): #{unknown.join(', ')}. " \
+              "allowed: #{UPDATABLE_FIELDS.join(', ')} (append_only/format are not updatable)"
+      end
+      if fields.key?(:title) && !fields.key?(:body)
+        raise ArgumentError,
+              "changing the title also rewrites the body — pass body: too. For metadata " \
+              "only, use folder/root/deadline/alert_email/webhook_* without title."
+      end
+
+      note = {}
+      note[:title]      = fields[:title] if fields.key?(:title)
+      note[:plain_body] = fields[:body]  if fields.key?(:body)
+      if fields[:root]
+        note[:folder_id] = nil
+      elsif fields.key?(:folder)
+        note[:folder_id] = resolve_folder_id(fields[:folder])
+      end
+      note[:append_deadline_hours] = fields[:deadline]       if fields.key?(:deadline)
+      note[:alert_email]           = fields[:alert_email]    if fields.key?(:alert_email)
+      note[:webhook_url]           = fields[:webhook_url]    if fields.key?(:webhook_url)
+      note[:webhook_secret]        = fields[:webhook_secret] if fields.key?(:webhook_secret)
+      raise ArgumentError, "no fields to update" if note.empty?
+
+      note
+    end
+
     def request(method, path, body = nil)
       uri = URI("#{@base_url}#{path}")
       req = Net::HTTP.const_get(method.to_s.capitalize).new(uri)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: freshjots
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.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: