samagotchi 0.110.0 → 0.111.0

data/lib/samagotchi/web/push/store.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "openssl"
+require "time"
+require "uri"
+require_relative "crypto"
+require_relative "../private_files"
+require_relative "../../atomic_file"
+require_relative "../../session"
+
+module Samagotchi
+  module Web
+    module Push
+      # This machine's Web Push state, in $XDG_STATE_HOME/samagotchi/web-push/
+      # (next to web-token and web-grants/; a 0700 folder, 0600 files, never
+      # in config.yml): vapid.pem, chi web's one VAPID key, and
+      # subscriptions.json, the devices that turned the bell on. A
+      # subscription holds no personal data (an opaque endpoint and two
+      # keys); the endpoint and keys never leave this store but for the push
+      # itself: what the page and the log show is Sub#public_h (the short
+      # id, the label, the dates). See docs/internals/web-push.md.
+      #
+      # chi web's request threads and the Notifier's sender thread both
+      # write: every write is a read-change-write under a lock file.
+      class Store
+        DIR = "web-push"
+        KEY_FILE = "vapid.pem"
+        SUBS_FILE = "subscriptions.json"
+        LOCK = "store.lock"
+
+        # The push services a subscription's endpoint may name: the
+        # browsers' (Apple, Google, Mozilla, Microsoft). chi web POSTs to
+        # nothing else (a subscription is the owner's, but an endpoint is a
+        # URL chi web fetches). A ".suffix" entry takes any host under it.
+        PUSH_SERVICES = ["web.push.apple.com", "fcm.googleapis.com", "updates.push.services.mozilla.com",
+                         ".notify.windows.com"].freeze
+        ENDPOINT_MAX = 2048
+        LABEL_MAX = 40
+        # Devices a store keeps (every subscribe adds one until it is turned
+        # off): a bound on what one push fans out to.
+        MAX_SUBS = 50
+
+        # The store's folder or a file in it can be read by others: chi web
+        # refuses to start (Server.launch).
+        class Insecure < StandardError; end
+
+        # A subscription the store won't take: the message is the page's.
+        class Invalid < StandardError; end
+
+        # subscriptions.json is there but doesn't read: no device is pushed
+        # to, and nothing writes over it (that would forget every device).
+        class Corrupt < StandardError
+          def initialize(path, reason)
+            super("#{path} can't be read (#{reason}): chi won't write over it; fix it, or move it aside and turn " \
+                  "the bell on again on each device")
+          end
+        end
+
+        # One device's subscription. +id+ is the short id (the first 8 hex
+        # of the endpoint's SHA-256), the only name of it outside this
+        # store. +p256dh+ and +auth+ as the browser gave them (base64url).
+        # +origin+ the public origin it subscribed on: it is sent to only
+        # while chi web runs there (a renamed machine's are stale).
+        Sub = Data.define(:id, :endpoint, :p256dh, :auth, :origin, :label, :created_at, :last_ok_at, :last_error,
+                          :prefs) do
+          def self.from_store(hash)
+            keys = hash["keys"].is_a?(Hash) ? hash["keys"] : {}
+            new(id: hash["id"], endpoint: hash["endpoint"], p256dh: keys["p256dh"], auth: keys["auth"],
+                origin: hash["origin"], label: hash["label"], created_at: hash["created_at"],
+                last_ok_at: hash["last_ok_at"], last_error: hash["last_error"],
+                prefs: hash["prefs"].is_a?(Hash) ? hash["prefs"] : { "done" => false })
+          end
+
+          def to_store
+            { "id" => id, "endpoint" => endpoint, "keys" => { "p256dh" => p256dh, "auth" => auth }, "origin" => origin,
+              "label" => label, "created_at" => created_at, "last_ok_at" => last_ok_at, "last_error" => last_error,
+              "prefs" => prefs }
+          end
+
+          # The device's keys as bytes (Crypto.encrypt's).
+          def p256dh_bytes = Crypto.unb64u(p256dh)
+          def auth_bytes = Crypto.unb64u(auth)
+
+          # Never the endpoint or the keys: what the page, the CLI and the log show.
+          def public_h
+            { id: id, label: label, origin: origin, created_at: created_at, last_ok_at: last_ok_at,
+              last_error: last_error }
+          end
+
+          def inspect = "#<Sub #{id} #{label.inspect}>"
+          alias_method :to_s, :inspect
+        end
+
+        # $XDG_STATE_HOME/samagotchi/web-push, next to the grants;
+        # +state_dir+ is the sessions dir (Session.default_state_dir).
+        def self.dir(state_dir: nil, env: ENV)
+          File.join(File.dirname(state_dir || Session.default_state_dir(env: env)), DIR)
+        end
+
+        def self.short_id(endpoint) = Digest::SHA256.hexdigest(endpoint.to_s)[0, 8]
+
+        attr_reader :dir
+
+        # @param services [Array<String>] the push services endpoints may
+        #   name (PUSH_SERVICES; a spec seam, not config)
+        # @param clock [#call] the Time now
+        def initialize(dir = Store.dir, services: PUSH_SERVICES, clock: -> { Time.now })
+          @dir = dir
+          @services = services
+          @clock = clock
+          @key_mutex = Mutex.new
+          @key = nil
+        end
+
+        # Never the key.
+        def inspect = "#<#{self.class.name} #{@dir}>"
+        alias to_s inspect
+
+        def key_path = File.join(@dir, KEY_FILE)
+        def subs_path = File.join(@dir, SUBS_FILE)
+
+        # Refuses a store others could read (PrivateFiles).
+        # @raise [Insecure]
+        def check_permissions!
+          PrivateFiles.check!(@dir, [key_path, subs_path], holds: "chi's push key and devices", error: Insecure)
+        end
+
+        # chi web's VAPID key: vapid.pem, made (0600) the first time.
+        # @return [OpenSSL::PKey::EC]
+        def vapid_key
+          @key_mutex.synchronize do
+            @key ||= locked do
+              if File.file?(key_path)
+                OpenSSL::PKey::EC.new(File.read(key_path))
+              else
+                Crypto.generate_key.tap { |key| AtomicFile.write(key_path, key.private_to_pem, perm: 0o600) }
+              end
+            end
+          end
+        end
+
+        # @return [Array<Sub>] none when the file is missing or corrupt (a
+        #   corrupt one is refused on write: #update)
+        def subscriptions
+          read
+        rescue Corrupt
+          []
+        end
+
+        # The subscriptions for +origin+ (the ones chi web sends to now).
+        def for_origin(origin) = subscriptions.select { |sub| sub.origin == origin }
+
+        def find(id) = subscriptions.find { |sub| sub.id == id }
+
+        # Adds the subscription a page's pushManager.subscribe gave (its
+        # JSON: endpoint, keys {p256dh, auth}); the same endpoint again
+        # replaces the old entry (a device subscribing again).
+        # @return [Sub]
+        # @raise [Invalid] one message per refusal
+        def add(subscription, origin:, label:)
+          endpoint, p256dh, auth = validate(subscription)
+          at = stamp(now)
+          sub = Sub.new(id: Store.short_id(endpoint), endpoint: endpoint, p256dh: p256dh, auth: auth, origin: origin,
+                        label: label.to_s[0, LABEL_MAX], created_at: at, last_ok_at: nil, last_error: nil,
+                        prefs: { "done" => false })
+          update do |subs|
+            kept = subs.reject { |old| old.endpoint == endpoint }
+            raise Invalid, "chi web already pushes to #{MAX_SUBS} devices: turn the bell off on one first" if kept.size >= MAX_SUBS
+
+            [kept + [sub], sub]
+          end
+        end
+
+        # Removes the subscription with this short id or endpoint.
+        # @return [Sub, nil] the one removed
+        def remove(id_or_endpoint)
+          update do |subs|
+            gone = subs.find { |sub| sub.id == id_or_endpoint || sub.endpoint == id_or_endpoint }
+            [subs - [gone], gone]
+          end
+        end
+
+        # Records a delivery: +ok+ true stamps last_ok_at (and clears the
+        # error), else +error+ (a short word: "410", "timeout") is kept.
+        def mark(id, ok: false, error: nil)
+          update do |subs|
+            subs = subs.map do |sub|
+              next sub unless sub.id == id
+
+              ok ? sub.with(last_ok_at: stamp(now), last_error: nil) : sub.with(last_error: error.to_s[0, 80])
+            end
+            [subs, nil]
+          end
+        end
+
+        private
+
+        def now = @clock.call
+
+        def stamp(time) = time.utc.iso8601
+
+        # @return [Array(String, String, String)] endpoint, p256dh, auth
+        def validate(subscription)
+          keys = subscription["keys"] if subscription.is_a?(Hash)
+          endpoint = subscription["endpoint"] if subscription.is_a?(Hash)
+          unless endpoint.is_a?(String) && keys.is_a?(Hash) && keys["p256dh"].is_a?(String) && keys["auth"].is_a?(String)
+            raise Invalid, "a push subscription needs an endpoint and keys (p256dh, auth)"
+          end
+
+          check_endpoint(endpoint)
+          p256dh = decoded(keys["p256dh"])
+          unless p256dh&.bytesize == 65 && p256dh.getbyte(0) == 4
+            raise Invalid, "a push subscription's p256dh must be a P-256 public key (65 bytes, base64url)"
+          end
+          raise Invalid, "a push subscription's auth must be 16 bytes (base64url)" unless decoded(keys["auth"])&.bytesize == 16
+
+          [endpoint, keys["p256dh"], keys["auth"]]
+        end
+
+        def check_endpoint(endpoint)
+          uri = begin
+            URI.parse(endpoint)
+          rescue URI::InvalidURIError
+            nil
+          end
+          if endpoint.bytesize > ENDPOINT_MAX || uri.nil? || uri.scheme != "https" || uri.host.to_s.empty? ||
+             uri.userinfo || uri.port != 443
+            raise Invalid, "a push endpoint must be an https URL on port 443"
+          end
+          return if service?(uri.host.downcase)
+
+          raise Invalid, "chi web only pushes to the browsers' push services, not #{uri.host[0, 80]}"
+        end
+
+        def service?(host)
+          @services.any? { |entry| entry.start_with?(".") ? host.end_with?(entry) && host.length > entry.length : host == entry }
+        end
+
+        def decoded(text)
+          Crypto.unb64u(text)
+        rescue ArgumentError
+          nil
+        end
+
+        # @raise [Corrupt]
+        def read
+          data = begin
+            JSON.parse(File.read(subs_path))
+          rescue Errno::ENOENT
+            return []
+          rescue JSON::ParserError
+            raise Corrupt.new(subs_path, "not JSON")
+          end
+          rows = data["subscriptions"] if data.is_a?(Hash)
+          raise Corrupt.new(subs_path, "no subscriptions list") unless rows.is_a?(Array) && rows.all?(Hash)
+
+          rows.map { |row| Sub.from_store(row) }
+        end
+
+        # Read, change and write subscriptions.json under the lock. The block
+        # takes the subscriptions and returns [new subscriptions, result].
+        def update
+          locked do
+            subs, result = yield(read)
+            body = JSON.pretty_generate({ "version" => 1, "subscriptions" => subs.map(&:to_store) })
+            AtomicFile.write(subs_path, "#{body}\n", perm: 0o600)
+            result
+          end
+        end
+
+        def locked
+          FileUtils.mkdir_p(@dir, mode: 0o700)
+          File.chmod(0o700, @dir)
+          File.open(File.join(@dir, LOCK), File::RDWR | File::CREAT, 0o600) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/web/push.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "push/crypto"
+require_relative "push/store"
+require_relative "push/client"
+require_relative "push/attention"
+require_relative "push/notifier"
+require_relative "../config"
+
+module Samagotchi
+  module Web
+    # Web Push: chi web reaches the owner's phone (a Home Screen app that
+    # turned the bell on) when a session waits on an approval or a question.
+    # It needs an https public origin (web.public_url or chi web --tunnel
+    # tailscale) and web.push.enabled (on by default); without a subscribed
+    # device it does nothing. See docs/configuration.md (Phone
+    # notifications) and docs/internals/web-push.md.
+    module Push
+      # chi web won't start with push as configured: a web.push.contact
+      # Apple would refuse, or a key it can't read.
+      class Refused < StandardError; end
+
+      # What chi web's push routes and its Notifier share for one run: the
+      # store, the client that signs with its key, and the public origin
+      # the devices subscribe on.
+      Runtime = Data.define(:store, :client, :origin)
+
+      module_function
+
+      # Push runs for +public_url+ (nil: none) when web.push.enabled.
+      def active?(public_url) = !public_url.nil? && Config.get("web.push.enabled") != false
+
+      # The VAPID sub: web.push.contact, else the public origin.
+      # @raise [Refused] a contact that isn't a mailto: or https URL
+      def contact(origin)
+        given = Config.get("web.push.contact").to_s.strip
+        return origin if given.empty?
+        return given if Crypto.valid_sub?(given)
+
+        raise Refused, "web.push.contact must be a mailto: address or an https URL (the push services refuse " \
+                       "anything else), not #{given[0, 80]}"
+      end
+
+      # Server.launch's check, before a tunnel goes up: the contact, the
+      # store's permissions and its key (made the first time).
+      # @raise [Refused, Store::Insecure]
+      def preflight!(public_url, store: Store.new)
+        return unless active?(public_url)
+
+        contact(public_url.origin)
+        store.check_permissions!
+        load_key(store)
+      end
+
+      # @raise [Refused] vapid.pem is there but isn't a key
+      def load_key(store)
+        store.vapid_key
+      rescue OpenSSL::PKey::PKeyError => e
+        raise Refused, "#{store.key_path} isn't a key chi can read (#{e.message[0, 80]}): move it aside and turn " \
+                       "the bell on again on each device"
+      end
+
+      # This run's Runtime, nil when push is off.
+      def runtime(public_url, state_dir: nil)
+        return nil unless active?(public_url)
+
+        store = Store.new(Store.dir(state_dir: state_dir))
+        Runtime.new(store: store, client: Client.new(key: load_key(store), contact: contact(public_url.origin)),
+                    origin: public_url.origin)
+      end
+    end
+  end
+end

data/lib/samagotchi/web/push_routes.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "push"
+
+module Samagotchi
+  module Web
+    # The owner's Web Push routes (App::ROUTES, all :owner rows: a
+    # participant gets no pushes): what the page's bell asks (GET /api/push),
+    # subscribing this device and unsubscribing it, and a test push.
+    # Included in App: its helpers (json_response, error_response,
+    # parse_json, request_body) and @push (a Push::Runtime, nil when push is
+    # off: no https public_url, or web.push.enabled false) answer. See
+    # docs/internals/web-push.md.
+    module PushRoutes
+      PUSH_BODY_LIMIT = 8192
+
+      private
+
+      # {enabled, public_key, origin, this}: +this+ is the device whose
+      # endpoint the page sends as ?endpoint= (its pushManager's), nil when
+      # this store doesn't have it for this origin.
+      def handle_push_info(req)
+        return json_response(200, { enabled: false, public_key: nil, origin: nil, this: nil }) unless @push
+
+        endpoint = req.params["endpoint"].to_s
+        this = endpoint.empty? ? nil : @push.store.for_origin(@push.origin).find { |sub| sub.endpoint == endpoint }
+        json_response(200, { enabled: true, public_key: Push::Crypto.public_key_b64(@push.store.vapid_key),
+                             origin: @push.origin, this: this && { id: this.id, label: this.label } })
+      end
+
+      # {subscription: {endpoint, keys: {p256dh, auth}}} → 201 {id, label}.
+      def handle_push_subscribe(req)
+        return push_off unless @push
+
+        body = push_body(req)
+        return error_response(400, "invalid_json", "invalid JSON body") unless body.is_a?(Hash)
+
+        sub = @push.store.add(body["subscription"], origin: @push.origin, label: device_label(req))
+        Log.info(:web, "push_subscribed", device: sub.id)
+        json_response(201, { id: sub.id, label: sub.label })
+      rescue Push::Store::Invalid => e
+        error_response(400, "invalid_subscription", e.message)
+      end
+
+      # {endpoint} → 204: this device's bell turned off.
+      def handle_push_unsubscribe(req)
+        return push_off unless @push
+
+        body = push_body(req)
+        endpoint = body["endpoint"] if body.is_a?(Hash)
+        return error_response(400, "missing_fields", "endpoint is required") unless endpoint.is_a?(String) && !endpoint.empty?
+
+        gone = @push.store.remove(endpoint)
+        Log.info(:web, "push_unsubscribed", device: gone.id) if gone
+        [204, { "Cache-Control" => "no-store" }, []]
+      end
+
+      # {endpoint?} → a test push to that device (or every one on this
+      # origin), answered with each device's result.
+      def handle_push_test(req)
+        return push_off unless @push
+
+        body = push_body(req)
+        endpoint = body["endpoint"] if body.is_a?(Hash)
+        subs = @push.store.for_origin(@push.origin)
+        subs = subs.select { |sub| sub.endpoint == endpoint } if endpoint.is_a?(String) && !endpoint.empty?
+        payload = { v: 1, kind: "show", tag: "chi:test", title: "chi", body: "test notification", url: "/" }
+        results = subs.map do |sub|
+          result = @push.client.deliver(sub, payload, ttl: 600, urgency: "high")
+          Log.info(:web, "push_test", device: sub.id, code: result.code, ms: result.ms)
+          @push.store.remove(sub.id) if result.status == :gone
+          { id: sub.id, label: sub.label, status: result.status.to_s, code: result.code, ms: result.ms }
+        end
+        json_response(200, { devices: results })
+      end
+
+      def push_off
+        error_response(409, "push_off", "push needs an https public URL (chi web --tunnel tailscale, or web.public_url) " \
+                                        "and web.push.enabled")
+      end
+
+      def push_body(req) = parse_json(request_body(req, PUSH_BODY_LIMIT))
+
+      # chi's own name for the device (a subscription carries none): its
+      # class from the User-Agent (iOS's is frozen, so it is generic) and
+      # the date.
+      def device_label(req)
+        agent = req.get_header("HTTP_USER_AGENT").to_s
+        kind = if agent.include?("iPhone") then "iPhone"
+               elsif agent.include?("iPad") then "iPad"
+               elsif agent.include?("Macintosh") then "Mac"
+               else "Browser"
+               end
+        "#{kind} · #{Time.now.strftime("%Y-%m-%d")}"
+      end
+    end
+  end
+end

data/lib/samagotchi/web/server.rb

@@ -12,6 +12,7 @@ require_relative "lan"
 require_relative "link_codes"
 require_relative "proxy_gate"
 require_relative "public_url"
+require_relative "push"
 require_relative "qr"
 require_relative "running"
 require_relative "session_hub"
@@ -121,6 +122,10 @@ module Samagotchi
           end
           # The participants' grants: never served from a store others can read.
           Grants.check_permissions!(Grants.path)
+          # Web Push (with an https public_url): a contact the push services
+          # would refuse, or a key store others can read, stops it here,
+          # before any tunnel goes up.
+          Push.preflight!(public_url)
           options = { port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, view: view,
                       annotate_presets: annotate_presets, editor: editor, lan: lan, working_set: working_set,
                       public_url: public_url }
@@ -131,7 +136,7 @@ module Samagotchi
                     end
           started ? 0 : 1
         end
-      rescue Lan::Error, Grants::Insecure, PublicUrl::Invalid, Tunnel::Refused => e
+      rescue Lan::Error, Grants::Insecure, PublicUrl::Invalid, Tunnel::Refused, Push::Refused, Push::Store::Insecure => e
         warn "Error: #{e.message}"
         1
       rescue Interrupt
@@ -198,9 +203,10 @@ module Samagotchi
         Token.load_or_create(token_path) if lan || public_url
         lan_option = { ip: lan.ip, token: Token::Source.new(token_path) } if lan
         public_token = Token::Source.new(token_path) if public_url
+        push = push_runtime(public_url, state_dir)
         app = App.new(manager: manager, state_dir: state_dir, markdown: markdown, view: view,
                       annotate_presets: annotate_presets, editor: editor, hub: hub, lan: lan_option, working_set: working_set,
-                      public_url: public_url, public_token: public_token)
+                      public_url: public_url, public_token: public_token, push: push)
         Samagotchi::Log.info(:web, "start", url: "http://#{host}:#{port}", version: Samagotchi::VERSION)
         Samagotchi::Log.info(:web, "lan", ip: lan.ip, interface: lan.interface) if lan
         if public_url
@@ -209,6 +215,13 @@ module Samagotchi
         end
         # Subscribed before the first scan, which makes the first check.
         hub.subscribe(method(:on_hub_event))
+        if push
+          # The Notifier seeds from the hub's snapshot, which is empty before
+          # a scan: one now, so what is already open never pushes.
+          hub.scan
+          notifier = Push::Notifier.new(store: push.store, client: push.client, origin: push.origin).start(hub)
+          Samagotchi::Log.info(:web, "push", devices: push.store.for_origin(push.origin).size)
+        end
         hub.start
         # Said once the port is bound: a second chi web racing for it gets
         # the in-use line instead.
@@ -249,12 +262,23 @@ module Samagotchi
       ensure
         Running.clear(path: running_path) if running_path
         config_restart_unsubscribe&.call
+        notifier&.stop
         hub&.stop
         Samagotchi::Log.info(:web, "stop") if app
       end
 
       class LanListenError < StandardError; end
 
+      # This run's Web Push (Push.runtime), nil when off. launch checked it
+      # (Push.preflight!); a store that broke since leaves chi web running
+      # without pushes, said in one line.
+      def self.push_runtime(public_url, state_dir)
+        Push.runtime(public_url, state_dir: state_dir)
+      rescue Push::Refused, Push::Store::Insecure, SystemCallError => e
+        Samagotchi::Log.warn(:web, "push_off", echo: "Warning: #{e.message}; phone notifications are off")
+        nil
+      end
+
       # Where this chi web listens, and its public_url (config's or the
       # tunnel's), for chi share's link (Web::Running); a write that fails
       # leaves the server running and the readers on web.port and config.