ruby_everywhere 0.6.0 → 0.8.0

data/lib/everywhere/commands/release.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require "dry/cli"
+require "digest"
+require "json"
 require_relative "../shellout"
+require_relative "../host"
 require_relative "../log_filter"
 require_relative "../receipt"
 require_relative "../paths"
@@ -17,75 +20,181 @@ module Everywhere
     # surface (local, CI, Platform) must produce. See
     # platform/docs/build-engine.md §4, §7, §9.
     #
-    # Today only the macos builder is live; the target is parameterized so
-    # ios/android/windows/linux slot in as builders later.
+    # macos/ios/android are live; windows/linux slot in as builders later.
     class Release < Dry::CLI::Command
       NOTARIZE = File.expand_path("../../../support/release/macos/notarize.sh", __dir__)
 
+      # What counts as "the distributable" per os, newest first when several
+      # match. Android is listed aab-then-apk so a `--format aab` run picks the
+      # bundle even when an older apk is still sitting in dist/.
+      ARTIFACTS = { "macos" => %w[*.zip], "ios" => %w[*.ipa], "android" => %w[*.aab *.apk] }.freeze
+
       desc "Sign, notarize, staple, and emit release.json for a distributable build"
 
       option :root,       default: ".",              desc: "App root directory"
-      option :target,     default: "macos-arm64",    desc: "Build target (os-arch)"
+      option :target,     default: Build::DEFAULT_TARGET, desc: "Build target (os-arch)"
       option :channel,    default: "direct",         desc: "Distribution channel (direct | mac_app_store | ...)"
       option :ruby,       default: nil,              desc: "Ruby version to package (default: build.ruby or 4.0.6)"
       option :entry,      default: "native_boot.rb", desc: "Entry point script relative to root"
       option :app_name,   default: nil,              desc: "Bundle name (default from config)"
       option :shell_dir,  default: nil,              desc: "Path to the shell's src-tauri directory"
       option :env_file,   default: nil,              desc: "dotenv file with APPLE_* signing secrets (default: .env.release)"
-      option :skip_build, type: :boolean, default: false, desc: "Notarize the existing .app instead of rebuilding"
+      option :format,     default: "apk",            desc: "Android artifact format (apk | aab)"
+      option :skip_build, type: :boolean, default: false, desc: "Sign the existing build instead of rebuilding"
 
-      def call(root: ".", target: "macos-arm64", channel: "direct", ruby: nil, entry: "native_boot.rb",
-               app_name: nil, shell_dir: nil, env_file: nil, skip_build: false, **)
+      def call(root: ".", target: Build::DEFAULT_TARGET, channel: "direct", ruby: nil, entry: "native_boot.rb",
+               app_name: nil, shell_dir: nil, env_file: nil, format: "apk", skip_build: false, **)
         root_path = File.expand_path(root)
         config = Everywhere::Config.load(root_path)
         app_name ||= config.name(target: target)
         ruby ||= config.build_ruby || "4.0.6"
+        os = Everywhere::Config.os_of(target)
 
-        preflight!(target)
+        preflight!(target, os)
 
         framework = config.remote? ? nil : Framework.detect(root_path)
         dist_dir = File.expand_path("dist", root_path)
 
-        # 1. Produce (or reuse) the signed-for-dev .app via the build path. The
-        #    notarize step below re-signs it inside-out with the Developer ID.
+        # 1. Produce (or reuse) the build. macOS gets a dev-signed .app that the
+        #    notarize step re-signs inside-out with the Developer ID; the mobile
+        #    toolchains sign as they build, so their artifact is already final.
         unless skip_build
           UI.phase("Building #{app_name} for #{UI.target_label(target)}")
-          Build.new.call(root: root, ruby: ruby, entry: entry, app_name: app_name, target: target, shell_dir: shell_dir, **)
+          Build.new.call(root: root, ruby: ruby, entry: entry, app_name: app_name, target: target,
+                         shell_dir: shell_dir, **, **build_options(os, format, channel))
+        end
+
+        # 2. Sign/notarize (macOS) or locate what the mobile builder signed, then
+        #    3. record the signing facts and emit the receipt.
+        artifact, signing = case os
+                            when "macos" then notarize!(dist_dir, root_path, env_file)
+                            when "ios"   then [find_artifact(dist_dir, os), ios_signing(dist_dir)]
+                            else              [find_artifact(dist_dir, os), android_signing]
+                            end
+
+        receipt = Receipt.new(root: root_path, config: config, framework: framework, ruby: ruby,
+                              target: target, channel: channel, shell_dir: resolve_shell_dir(shell_dir))
+        out = File.join(dist_dir, "release.json")
+        receipt.write(out, artifact: artifact, signing: signing)
+
+        summarize(out, artifact, signing, root_path)
+      end
+
+      private
+
+      def preflight!(target, os)
+        case os
+        when "macos"
+          UI.die!("`every release --target #{target}` runs on macOS only") unless Host.darwin?
+          UI.die!("signing engine missing at #{NOTARIZE}") unless File.exist?(NOTARIZE)
+        when "ios"
+          UI.die!("iOS releases need Xcode — `every release --target #{target}` runs on macOS only") unless Host.darwin?
+        when "android"
+          nil # Gradle signs and builds anywhere the Android SDK does — Linux included.
+        else
+          UI.die!("no release builder for #{target} — macos-*, ios-* and android-* are supported")
         end
+      end
+
 
+      # Only the flag that belongs to this os: `every build` rejects the other.
+      # iOS also needs the channel: a testflight/app_store release uploads to App
+      # Store Connect from the build host, which only the builder can do.
+      def build_options(os, format, channel)
+        case os
+        when "ios"     then { device: true, channel: channel } # a release is always a device .ipa, never a simulator .app
+        when "android" then { format: format }
+        else {}
+        end
+      end
+
+      # macOS: sign (Developer ID + hardened runtime) → notarize → staple → verify,
+      # then read the signing facts back off the bundle.
+      def notarize!(dist_dir, root_path, env_file)
         app_dir = Dir[File.join(dist_dir, "*.app")].max_by { |d| File.mtime(d) }
         UI.die!("no .app found in #{dist_dir} — run without --skip-build first") unless app_dir
 
-        # 2. Sign (Developer ID + hardened runtime) → notarize → staple → verify.
         env_file ||= discover_env_file(root_path)
         env = env_file ? { "ENV_FILE" => env_file } : {}
         UI.phase("Signing & notarizing #{File.basename(app_dir)}")
-        UI.step("preparing #{File.basename(app_dir)}#{env_file ? " #{UI.dim("(env: #{rel(env_file, root_path)})")}" : ""}")
+        UI.step("preparing #{File.basename(app_dir)}")
+        # Named in full: these are the Apple credentials the notarization runs
+        # with, and "which file did that come from" is the first thing you ask
+        # when a build signs as the wrong team.
+        UI.detail("signing env: #{UI.short_path(File.expand_path(env_file))}") if env_file
         UI.warn("no signing env found — set APPLE_* or pass --env-file (notarize.sh will fail without it)") unless env_file || ENV["APPLE_SIGNING_IDENTITY"]
         log = "#{app_dir}.notarize.log"
         Shellout.run_logged!(env, ["/bin/bash", NOTARIZE, app_dir], log: log, filter: LogFilter.for(:notarize))
 
-        # 3. Gather signing facts from the bundle itself, then emit the receipt.
         artifact = "#{app_dir.sub(/\.app\z/, "")}.zip" # notarize.sh re-zips the stapled app
         UI.die!("expected notarized zip #{artifact} not found") unless File.exist?(artifact)
-        artifact = dashify(artifact)
 
-        signing = gather_signing(app_dir, log)
-        receipt = Receipt.new(root: root_path, config: config, framework: framework, ruby: ruby,
-                              target: target, channel: channel, shell_dir: resolve_shell_dir(shell_dir))
-        out = File.join(dist_dir, "release.json")
-        receipt.write(out, artifact: artifact, signing: signing)
+        [dashify(artifact), gather_signing(app_dir, log)]
+      end
 
-        summarize(out, artifact, signing, root_path)
+      # The mobile artifact ships as-is — no zip, no rename: an .ipa/.apk/.aab is
+      # already the installable container the stores and devices expect.
+      def find_artifact(dist_dir, os)
+        patterns = ARTIFACTS.fetch(os)
+        found = patterns.filter_map { |p| Dir[File.join(dist_dir, p)].max_by { |f| File.mtime(f) } }.first
+        return found if found
+
+        UI.die!("no #{patterns.map { |p| p.delete("*") }.join(" or ")} found in #{dist_dir} — " \
+                "run without --skip-build first")
       end
 
-      private
+      # Reaching this line IS the verification for iOS: xcodebuild -exportArchive
+      # refuses to emit an .ipa it couldn't sign with the requested profile, so
+      # there's nothing left to probe (and no spctl/stapler for a mobile bundle).
+      def ios_signing(dist_dir)
+        {
+          "signed" => true,
+          "signed_by" => ENV["EVERY_IOS_TEAM_ID"],
+          "verified" => true,
+          "platform" => {
+            "provisioning_profile" => ENV["EVERY_IOS_PROVISIONING_PROFILE"],
+            "distribution_method" => ENV["EVERY_IOS_EXPORT_METHOD"] || "app-store-connect",
+            "upload" => upload_bag(dist_dir)
+          }.compact
+        }
+      end
+
+      # dist/ios-upload.json is written by Builders::Ios only after the App Store
+      # Connect upload pass succeeded — so it's absent (and the key compacted
+      # away) for every non-store channel. This is the contract the Platform's
+      # store distributors read back out of the receipt.
+      def upload_bag(dist_dir)
+        path = File.join(dist_dir, "ios-upload.json")
+        return nil unless File.exist?(path)
 
-      def preflight!(target)
-        os = target.split("-", 2).first
-        UI.die!("only the macos target is implemented (got #{target}); other builders are stubs") unless os == "macos"
-        UI.die!("`every release` runs on macOS only") unless RUBY_PLATFORM.include?("darwin")
-        UI.die!("signing engine missing at #{NOTARIZE}") unless File.exist?(NOTARIZE)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Gradle only signs when a keystore was handed to it; without one it still
+      # produces a (debug/unsigned) artifact, so the receipt has to say which.
+      def android_signing
+        keystore = ENV["EVERY_ANDROID_KEYSTORE"]
+        fingerprint = keystore_fingerprint(keystore)
+        {
+          "signed" => !fingerprint.nil?,
+          "signed_by" => fingerprint,
+          "verified" => !fingerprint.nil?,
+          "platform" => {
+            "signing_scheme" => fingerprint ? "v2" : "unsigned",
+            "keystore_fingerprint" => fingerprint
+          }.compact
+        }
+      end
+
+      # The file digest, not keytool's certificate fingerprint: it identifies the
+      # keystore that signed this build without shelling out to the JDK (which the
+      # runner may not have on PATH) or unlocking it with the store password.
+      def keystore_fingerprint(keystore)
+        return nil if keystore.nil? || keystore.empty? || !File.exist?(keystore)
+
+        "sha256:#{Digest::SHA256.file(keystore).hexdigest}"
       end
 
       # The distributable filename must be URL/CI-safe, so spaces become dashes
@@ -97,10 +206,11 @@ module Everywhere
         dashed
       end
 
-      # A .env.release next to the app, then at the repo root above it.
+      # A .env.release next to the app — and nowhere else. The parent directory
+      # used to be searched too, which meant a release could silently pick up
+      # Apple credentials from outside the project it was building.
       def discover_env_file(root_path)
-        [ENV["ENV_FILE"], File.join(root_path, ".env.release"), File.join(root_path, "..", ".env.release")]
-          .compact.find { |p| File.exist?(p) }
+        [ENV["ENV_FILE"], File.join(root_path, ".env.release")].compact.find { |p| File.exist?(p) }
       end
 
       def resolve_shell_dir(given)
@@ -138,15 +248,25 @@ module Everywhere
 
       def summarize(out, artifact, signing, root_path)
         UI.phase("Release ready 🎉")
-        UI.success("#{rel(artifact, root_path)} #{UI.dim("(#{(File.size(artifact) / 1024.0 / 1024.0).round}MB — send this to your friends)")}")
+        UI.success("#{UI.rel_path(artifact, root_path)} #{UI.dim("(#{(File.size(artifact) / 1024.0 / 1024.0).round}MB — send this to your friends)")}")
         UI.substep("signed by #{UI.bold(signing["signed_by"] || "?")}")
-        UI.substep("notarized #{UI.yn(signing.dig("platform", "notarized"))} · " \
-                   "stapled #{UI.yn(signing.dig("platform", "stapled"))} · " \
-                   "gatekeeper #{UI.yn(signing["verified"])}")
-        UI.substep("receipt #{UI.dim(rel(out, root_path))}")
+        UI.substep(signing_line(signing["platform"] || {}, signing))
+        UI.substep("receipt #{UI.dim(UI.rel_path(out, root_path))}")
       end
 
-      def rel(path, root_path) = UI.short_path(path.sub("#{root_path}/", "").sub("#{Dir.pwd}/", ""))
+      def signing_line(platform, signing)
+        if platform.key?("notarized")
+          "notarized #{UI.yn(platform["notarized"])} · stapled #{UI.yn(platform["stapled"])} · " \
+            "gatekeeper #{UI.yn(signing["verified"])}"
+        elsif platform.key?("distribution_method")
+          upload = platform["upload"]
+          "profile #{UI.bold(platform["provisioning_profile"] || "?")} · " \
+            "method #{platform["distribution_method"]}" \
+            "#{" · uploaded to App Store Connect (build #{upload["build_number"] || "?"})" if upload}"
+        else
+          "signing scheme #{UI.bold(platform["signing_scheme"] || "?")}"
+        end
+      end
     end
   end
 end

data/lib/everywhere/commands/shell_dir.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "dry/cli"
+require_relative "../config"
+require_relative "../paths"
 
 module Everywhere
   module Commands
@@ -12,9 +14,9 @@ module Everywhere
     class ShellDir < Dry::CLI::Command
       desc "Print the path of the bundled shell (Tauri src-tauri, or the iOS template)"
 
-      option :target, default: "macos-arm64", desc: "Build target (os or os-arch) selecting which shell"
+      option :target, default: "macos", desc: "Build target (os or os-arch) selecting which shell"
 
-      def call(target: "macos-arm64", **)
+      def call(target: "macos", **)
         case Everywhere::Config.os_of(target)
         when "ios" then puts Everywhere::Paths.ios_dir!
         else            puts Everywhere::Paths.shell_dir!

data/lib/everywhere/commands/updates_keygen.rb

@@ -31,14 +31,22 @@ module Everywhere
         end
 
         UI.phase("Generating update signing key for #{bundle_id}")
-        pair = Minisign.keygen(passphrase: passphrase ? prompt_passphrase : "")
+        secret = resolve_passphrase(passphrase)
+        pair = Minisign.keygen(passphrase: secret)
 
         require "fileutils"
         FileUtils.mkdir_p(keys_dir, mode: 0o700)
         File.write(sk_path, pair.secret_key, perm: 0o600)
         File.write(pub_path, pair.public_key, perm: 0o644)
+        # perm: only applies when the file is created — an overwrite (--force,
+        # or a key from an older version) keeps whatever mode it had.
+        File.chmod(0o600, sk_path)
 
         UI.ok("secret key #{UI.short_path(sk_path)} #{UI.dim("(key id #{pair.key_id_hex})")}")
+        if secret.empty?
+          UI.warn("this secret key is stored UNENCRYPTED — anyone who can read " \
+                  "#{UI.short_path(sk_path)} can sign updates your users will install")
+        end
         UI.ok("public key #{UI.short_path(pub_path)}")
 
         UI.phase("Add the public key to config/everywhere.yml")
@@ -54,6 +62,22 @@ module Everywhere
 
       private
 
+      # --passphrase insists on one. Without the flag we still ask whenever
+      # there's a terminal to ask on — an unencrypted signing key is a real
+      # choice (CI has to have one), but it shouldn't be what you get by
+      # forgetting a flag. Empty answer = unencrypted, and it's warned about.
+      def resolve_passphrase(flag)
+        return prompt_passphrase if flag
+        return "" unless $stdin.tty?
+
+        require "io/console"
+        pass = $stdin.getpass("Passphrase (empty for an unencrypted key): ")
+        return "" if pass.empty?
+
+        UI.die!("passphrases didn't match") unless pass == $stdin.getpass("Passphrase (again): ")
+        pass
+      end
+
       def prompt_passphrase
         require "io/console"
         UI.die!("--passphrase needs an interactive terminal") unless $stdin.tty?

data/lib/everywhere/config/app.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module App
+      def name(target: nil)
+        resolved(target)["name"] || File.basename(File.expand_path(root)).split(/[-_]/).map(&:capitalize).join(" ")
+      end
+
+      # Reverse-DNS identifier: macOS bundle id, and the name of the per-user
+      # app-data directory on every platform. Set it explicitly and never change
+      # it — renaming moves users' data. A platform may override it (e.g. the App
+      # Store often wants `com.example.app.ios`).
+      def bundle_id(target: nil)
+        resolved(target)["bundle_id"] ||
+          "com.rubyeverywhere.#{name(target: target).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")}"
+      end
+
+      # A bundle id isn't only an identifier: it's a path segment (Paths.*_work_dir,
+      # which the builders rm_rf, and the update-signing key on disk). The derived
+      # default is safe by construction; an explicit one is whatever the app repo
+      # says, so it's held to reverse-DNS characters and nothing else.
+      BUNDLE_ID = /\A[A-Za-z0-9][A-Za-z0-9.-]*\z/
+
+      def identity_errors
+        sections = [["app", app]] + platforms.map { |os, override| ["platforms.#{os}", override] }
+        sections.filter_map do |at, section|
+          next unless section.is_a?(Hash)
+
+          value = section["bundle_id"].to_s
+          next if value.empty? || (value.match?(BUNDLE_ID) && !value.include?(".."))
+
+          "#{at}.bundle_id #{value.inspect} is not a bundle id — reverse-DNS, " \
+            "letters/digits/./- only (like com.example.app)"
+        end
+      end
+
+      # App icon source: a PNG (ideally square, 1024px+). Explicit `app.icon`
+      # path relative to the app root, or icon.png at the root by convention.
+      def icon
+        if (explicit = app["icon"])
+          File.expand_path(explicit, root)
+        else
+          default = File.join(root, "icon.png")
+          File.exist?(default) ? default : nil
+        end
+      end
+
+      # Optional custom splash page (HTML file, path relative to the app root).
+      # Shown while the packaged server boots; the shell injects
+      # window.__EVERYWHERE_CONFIG__ so it can use the app's name and colors.
+      def splash
+        path = app["splash"]
+        File.expand_path(path, root) if path
+      end
+
+      def entry_path
+        path = app["entry_path"] || "/"
+        path.start_with?("/") ? path : "/#{path}"
+      end
+
+      # Marketing/display version of the app (CFBundleShortVersionString, and the
+      # `version` recorded in the build receipt). One shared `app.version` is the
+      # default for every target; a platform may override it when a store forces a
+      # different number. Defaults conservatively.
+      def version(target: nil)
+        resolved(target)["version"] || "0.1.0"
+      end
+
+      # The `build:` section — durable build knobs that were once `every build`
+      # flags (ruby, targets, capabilities). CLI flags still override per-run.
+      # See platform/docs/build-engine.md §2.
+      def build = @data.fetch("build", nil) || {}
+
+      # Ruby version to package. nil here means "let the CLI decide its default".
+      def build_ruby = build["ruby"]
+
+      # Desktop OS-integration capabilities the app declares (`build.capabilities`),
+      # as a plain list. Deliberately not called permissions: the top-level
+      # `permissions:` below is the mobile prompt declaration — a different shape
+      # for a different consumer — and while both were spelled "permissions" this
+      # accessor was silently redefined by that one and could never be read.
+      def build_capabilities = Array(build["capabilities"])
+
+      # Build targets as BARE os-arch strings — any ":<channel>" suffix is
+      # stripped. Callers treat these as filesystem/URL-safe identifiers
+      # (`every publish` derives S3 update-manifest key paths from the first one),
+      # so a suffix leaking through here would poison those paths. Use
+      # #build_target_specs when the channel matters.
+      def targets = build_target_specs.map { |t| t.to_s.split(":", 2).first }
+
+      # The raw `build.targets` entries, suffixes intact ("ios-arm64:testflight").
+      def build_target_specs = Array(build["targets"])
+
+      # "local"  — the app is tebako-pressed and runs on-device (default)
+      # "remote" — thin shell around an already-deployed app: no press, no sidecar
+      def mode
+        app["mode"] || (remote_url ? "remote" : "local")
+      end
+
+      def remote? = mode == "remote"
+
+      def remote_url
+        @data.dig("remote", "url")&.chomp("/")
+      end
+
+      # Multi-instance apps (`remote.instances: true`): the mobile shell boots
+      # into remote.url — a hosted instance-picker page — and lets that page
+      # re-root the app onto a chosen instance via Everywhere.instance.set,
+      # persisted across launches until Everywhere.instance.clear. Opt-in
+      # because it lets page JS repoint the whole app: apps that aren't
+      # multi-instance shouldn't carry that surface.
+      def remote_instances?
+        @data.dig("remote", "instances") == true
+      end
+
+      def tint_color
+        normalize_color(appearance["tint_color"])
+      end
+
+      def background_color
+        normalize_color(appearance["background_color"])
+      end
+    end
+  end
+end

data/lib/everywhere/config/auth.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module Auth
+      # Third-party sign-in (Sign in with Apple / Google / GitHub / anything
+      # OmniAuth speaks). Providers refuse to run — or run badly — inside an app's
+      # web view, so the mobile shell hands these paths to an
+      # ASWebAuthenticationSession instead, and the gem bridges the resulting
+      # session back into the app (see AuthHandoff).
+      #
+      #   auth:
+      #     oauth_paths:                # paths that begin a provider flow
+      #       - ^/auth/                 # unanchored regexes, like `rules:`
+      #     scheme: com.example.app     # callback scheme (default: the iOS bundle id)
+      #     cookies:                    # which cookies cross back into the app
+      #       except: ["_ga"]           #   (default: all of them)
+      #
+      # The app keeps its own auth: `auth:` declares nothing about providers,
+      # only which paths the shell must not open in its web view.
+      def auth = @data.fetch("auth", nil) || {}
+
+      # Paths that begin a third-party auth flow, as regex source strings matched
+      # against the request path. Declaring `auth:` at all opts in, defaulting to
+      # OmniAuth's `/auth/…` convention.
+      DEFAULT_OAUTH_PATHS = ["^/auth/"].freeze
+
+      def oauth_paths
+        return [] unless @data.key?("auth")
+
+        paths = Array(auth["oauth_paths"]).map { |p| p.to_s.strip }.reject(&:empty?)
+        paths.empty? ? DEFAULT_OAUTH_PATHS.dup : paths
+      end
+
+      def oauth?  = !oauth_paths.empty?
+
+      # Whether a request path starts a provider flow. Both halves of the system
+      # ask this — the middleware per request, the shell per visit proposal — so
+      # the patterns are compiled the same way on both sides (unanchored regex).
+      def oauth_path?(path)
+        # Compiled once per Config, not once per request: the middleware calls
+        # this on every navigation, and the instance it holds lives until
+        # everywhere.yml changes on disk. An unparseable pattern matches nothing
+        # (auth_errors is what reports it).
+        @oauth_regexps ||= oauth_paths.filter_map do |pattern|
+          Regexp.new(pattern)
+        rescue RegexpError
+          nil
+        end
+        @oauth_regexps.any? { |regexp| regexp.match?(path.to_s) }
+      end
+
+      # The custom URL scheme ASWebAuthenticationSession returns through. Defaults
+      # to the iOS bundle id — the convention, and already unique per app. Only
+      # the characters RFC 3986 allows in a scheme.
+      URL_SCHEME = /\A[a-zA-Z][a-zA-Z0-9+.-]*\z/
+
+      def auth_scheme
+        explicit = auth["scheme"].to_s.strip
+        explicit.empty? ? bundle_id(target: "ios") : explicit
+      end
+
+      # Cookie names to carry from the auth browser back into the app's web view,
+      # filtered by an optional allow/deny list. Everything the flow set is
+      # carried by default: the gem can't know which cookie an app's auth library
+      # signs its session with.
+      def auth_cookie?(name)
+        cookies = auth["cookies"]
+        return true unless cookies.is_a?(Hash)
+
+        only = Array(cookies["only"]).map(&:to_s)
+        return only.include?(name.to_s) unless only.empty?
+
+        !Array(cookies["except"]).map(&:to_s).include?(name.to_s)
+      end
+
+      # How long a minted handoff token stays valid. It travels device-locally
+      # (browser sheet → shell → web view), so seconds are plenty.
+      def auth_token_ttl = [(auth["token_ttl"] || 60).to_i, 5].max
+
+      def auth_errors
+        return [] unless @data.key?("auth")
+
+        errors = oauth_paths.filter_map do |pattern|
+          Regexp.new(pattern)
+          nil
+        rescue RegexpError => e
+          "auth.oauth_paths: #{pattern.inspect} is not a valid pattern (#{e.message})"
+        end
+
+        unless auth_scheme.match?(URL_SCHEME)
+          errors << "auth.scheme #{auth_scheme.inspect} is not a URL scheme (letters, digits, +, -, .)"
+        end
+        errors
+      end
+
+      # The auth subset the shell needs: which visits to divert into the auth
+      # session, and the scheme to bring the answer back through. nil (absent from
+      # everywhere.json) when the app declares no `auth:` — a shell that can't
+      # divert anything is a shell with no new surface.
+      def auth_shell_hash
+        return nil unless oauth?
+
+        { "oauth_paths" => oauth_paths, "scheme" => auth_scheme }
+      end
+    end
+  end
+end

data/lib/everywhere/config/data.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    # The plumbing every other section reads through: the raw `app:` and
+    # `appearance:` hashes, the per-platform overrides that sit on top of them,
+    # and the two value coercions shared across sections. Included first, so
+    # everything below it can call these.
+    module Data
+      private
+
+      def app = @data.fetch("app", nil) || {}
+      def appearance = @data.fetch("appearance", nil) || {}
+
+      # YAML's `yes`/`on` already parse as true, so anything that reaches here
+      # still not a boolean is a genuine mistake rather than a spelling of one.
+      # Deliberately not an endless def: `def f(v) = v if cond` parses as
+      # `(def f(v) = v) if cond`, which would define nothing when cond is false.
+      def boolean_or_nil(value)
+        value if value == true || value == false
+      end
+
+      def android_target?(target) = self.class.os_of(target) == "android"
+
+      # Per-platform overrides, keyed by os (macos / ios / android / windows /
+      # linux). Each value overrides the matching `app:` keys for that platform.
+      def platforms = @data.fetch("platforms", nil) || {}
+
+      # The app-level keys with the target's platform override merged on top.
+      # Blank override values are dropped (`.compact`) so they don't erase a
+      # default. Without a target — or without an override for that os — this is
+      # just the plain `app:` hash.
+      def resolved(target)
+        override = target && platforms[self.class.os_of(target)]
+        override.is_a?(Hash) ? app.merge(override.compact) : app
+      end
+
+      def normalize_color(value)
+        case value
+        when String
+          { "light" => value, "dark" => value }
+        when Hash
+          light = value["light"] || value["dark"]
+          dark  = value["dark"] || value["light"]
+          { "light" => light, "dark" => dark } if light
+        end
+      end
+    end
+  end
+end