rkseal 0.1.0

data/lib/rkseal/commands/list.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module RKSeal
+  module Commands
+    # Orchestrates the `rkseal list [namespace]` flow.
+    #
+    # Lists the SealedSecret CRD objects in the cluster (all namespaces, or a
+    # single one) as a kubectl-style table. Strictly read-only and metadata-only:
+    # it prints solely each object's namespace, name, derived scope, and age --
+    # NEVER any part of `spec.encryptedData` (not even its keys). No editor, no
+    # RAM workspace, no file is written.
+    #
+    # @example all namespaces
+    #   puts RKSeal::Commands::List.new.call
+    # @example one namespace
+    #   puts RKSeal::Commands::List.new(namespace: "app").call
+    class List
+      # @return [String, nil] the namespace filter, or nil for all namespaces.
+      attr_reader :namespace
+
+      # Column headers, in display order.
+      HEADERS = %w[NAMESPACE NAME SCOPE AGE].freeze
+
+      # Scope symbol -> the dashed display label shown in the SCOPE column.
+      SCOPE_LABELS = {
+        strict: "strict",
+        namespace_wide: "namespace-wide",
+        cluster_wide: "cluster-wide"
+      }.freeze
+
+      # @param namespace [String, nil] limit to this namespace; nil lists all.
+      # @param kubectl [RKSeal::Kubectl] cluster adapter (read only).
+      # @param now [Time] clock used to compute AGE (injectable for tests).
+      def initialize(namespace: nil, kubectl: Kubectl.new, now: Time.now)
+        @namespace = namespace
+        @kubectl = kubectl
+        @now = now
+      end
+
+      # Run the list flow: read the SealedSecrets and render the table.
+      #
+      # Side effects: a single read-only `kubectl get sealedsecret`. No editor,
+      # no workspace, no file write.
+      #
+      # @return [String] the table (or a friendly empty-list message) to print.
+      # @raise [RKSeal::CommandError] kubectl failed.
+      def call
+        @kubectl.ensure_available!
+        items = parse_items(@kubectl.list_sealedsecrets(namespace: @namespace))
+        return empty_message if items.empty?
+
+        render_table(items.map { |item| row_for(item) })
+      end
+
+      private
+
+      def parse_items(json)
+        doc = JSON.parse(json)
+        items = doc.is_a?(Hash) ? doc["items"] : nil
+        items.is_a?(Array) ? items : []
+      rescue JSON::ParserError => e
+        raise CommandError.new("kubectl did not return valid JSON: #{e.message}",
+                               command: "kubectl get sealedsecret")
+      end
+
+      # Build a single table row from one SealedSecret. Reads ONLY metadata --
+      # `spec` is never touched, so no encrypted material can leak.
+      def row_for(item)
+        metadata = item["metadata"] || {}
+        [
+          metadata["namespace"].to_s,
+          metadata["name"].to_s,
+          SCOPE_LABELS.fetch(Secret.scope_from_sealed_json(item)),
+          age_for(metadata["creationTimestamp"])
+        ]
+      end
+
+      # kubectl-style compact age (e.g. "3d", "5h", "2m", "10s") from an RFC3339
+      # creationTimestamp. Unknown/unparseable -> "<unknown>".
+      def age_for(timestamp)
+        return "<unknown>" if timestamp.nil? || timestamp.to_s.empty?
+
+        seconds = (@now - Time.parse(timestamp.to_s)).to_i
+        humanize_age(seconds)
+      rescue ArgumentError
+        "<unknown>"
+      end
+
+      def humanize_age(seconds)
+        seconds = 0 if seconds.negative?
+        case seconds
+        when 0...60 then "#{seconds}s"
+        when 60...3600 then "#{seconds / 60}m"
+        when 3600...86_400 then "#{seconds / 3600}h"
+        else "#{seconds / 86_400}d"
+        end
+      end
+
+      # Render rows as a left-aligned, space-padded table with a header line,
+      # matching kubectl's `get` output style.
+      def render_table(rows)
+        widths = column_widths(rows)
+        [HEADERS, *rows].map { |row| format_row(row, widths) }.join("\n")
+      end
+
+      def column_widths(rows)
+        HEADERS.each_index.map do |col|
+          [HEADERS[col], *rows.map { |row| row[col] }].map(&:length).max
+        end
+      end
+
+      # Pad every cell but the last to its column width (trailing column is left
+      # un-padded so there is no trailing whitespace), joined by three spaces.
+      def format_row(row, widths)
+        row.each_with_index.map do |cell, col|
+          col == row.length - 1 ? cell : cell.ljust(widths[col])
+        end.join("   ").rstrip
+      end
+
+      def empty_message
+        return "No SealedSecrets found." if @namespace.nil?
+
+        "No SealedSecrets found in namespace #{@namespace.inspect}."
+      end
+    end
+  end
+end

data/lib/rkseal/commands/reencrypt.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module RKSeal
+  module Commands
+    # Orchestrates the `rkseal reencrypt <namespace> <secret-name>` flow.
+    #
+    # Re-encrypts an existing SealedSecret onto the controller's newest sealing
+    # key without ever exposing plaintext (`kubeseal --re-encrypt`). The input is
+    # the SealedSecret itself, not the unsealed Secret -- so unlike `edit`, this
+    # flow never touches `$EDITOR`, a RAM workspace, or cluster Secret values.
+    #
+    # Input resolution, in order:
+    #   1. the local `<name>.yaml` in the output directory (a previous run);
+    #   2. otherwise the live SealedSecret via {RKSeal::Kubectl#get_sealedsecret}.
+    # If neither exists, fail fast and point the user at `create`.
+    #
+    # Deploy is opt-in and identical to `edit`: {RKSeal::ContextGuard} surfaces
+    # the active context and confirms before `kubectl apply` (skipped with
+    # `assume_yes`).
+    #
+    # @example refresh to the newest key, write only
+    #   RKSeal::Commands::Reencrypt.new(namespace: "app", name: "db").call
+    class Reencrypt
+      # @return [String]
+      attr_reader :namespace
+      # @return [String]
+      attr_reader :name
+      # @return [Boolean]
+      attr_reader :deploy
+
+      # @param namespace [String] target namespace (positional CLI arg).
+      # @param name [String] Secret name (positional CLI arg).
+      # @param deploy [Boolean] opt-in deploy after writing; defaults to false.
+      # @param assume_yes [Boolean] skip the deploy confirmation (with deploy:).
+      # @param kubectl [RKSeal::Kubectl] cluster adapter (read + apply).
+      # @param kubeseal [RKSeal::Kubeseal] sealing adapter (re-encrypt).
+      # @param context_guard [RKSeal::ContextGuard, nil] deploy gatekeeper; built
+      #   from kubectl + prompt when nil and a deploy is requested.
+      # @param prompt [Thor::Shell::Basic] shell for the deploy confirmation.
+      # @param output_dir [String] directory the manifest is read from / written
+      #   to (CWD).
+      def initialize(namespace:, name:, deploy: false, assume_yes: false,
+                     kubectl: Kubectl.new, kubeseal: Kubeseal.new,
+                     context_guard: nil, prompt: Thor::Shell::Basic.new,
+                     output_dir: Dir.pwd)
+        @namespace = namespace
+        @name = name
+        @deploy = deploy
+        @assume_yes = assume_yes
+        @kubectl = kubectl
+        @kubeseal = kubeseal
+        @context_guard = context_guard
+        @prompt = prompt
+        @output_dir = output_dir
+      end
+
+      # Run the re-encrypt flow end to end.
+      #
+      # Side effects: reads the local `<name>.yaml` or the cluster SealedSecret;
+      # shells out to `kubeseal --re-encrypt`; writes `<name>.yaml`; and, only
+      # when {#deploy} is true and the operator confirms, runs `kubectl apply`.
+      #
+      # @return [RKSeal::Commands::Result] outcome (written path, deployed?).
+      # @raise [RKSeal::NotFoundError] no local file and the SealedSecret is
+      #   absent from the cluster (message points at `create`).
+      # @raise [RKSeal::CommandError] kubectl/kubeseal failed.
+      def call
+        @kubectl.ensure_available!
+        @kubeseal.ensure_available!
+
+        reencrypted = @kubeseal.re_encrypt(source_sealed_yaml)
+        path = write_manifest(reencrypted)
+        deployed = @deploy && deploy_confirmed?
+        @kubectl.apply(file: path) if deployed
+        Result.new(secret_name: @name, namespace: @namespace, output_path: path, deployed: deployed)
+      end
+
+      private
+
+      # The SealedSecret to re-encrypt: prefer the local file, fall back to the
+      # cluster. A missing cluster SealedSecret surfaces as NotFoundError from the
+      # adapter, which we re-message to point at `create`.
+      def source_sealed_yaml
+        local = manifest_path
+        return File.read(local) if File.file?(local)
+
+        @kubectl.get_sealedsecret(name: @name, namespace: @namespace)
+      rescue NotFoundError
+        raise NotFoundError,
+              "No local #{@name}.yaml and no SealedSecret #{@name.inspect} in " \
+              "namespace #{@namespace.inspect}. Run `rkseal create` first."
+      end
+
+      def write_manifest(sealed_yaml)
+        File.write(manifest_path, sealed_yaml)
+        File.expand_path(manifest_path)
+      end
+
+      def manifest_path
+        File.join(@output_dir, "#{@name}.yaml")
+      end
+
+      # Whether to proceed with the deploy: --yes skips the prompt, otherwise the
+      # ContextGuard surfaces the active context and confirms.
+      def deploy_confirmed?
+        return true if @assume_yes
+
+        context_guard.confirm_deploy(secret_name: @name, namespace: @namespace)
+      end
+
+      def context_guard
+        @context_guard ||= ContextGuard.new(kubectl: @kubectl, prompt: @prompt)
+      end
+    end
+  end
+end

data/lib/rkseal/commands/result.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RKSeal
+  module Commands
+    # Immutable value object describing the outcome of a command flow, returned
+    # to the CLI so it can print a result without reaching into flow internals.
+    #
+    # Shared by {RKSeal::Commands::Create} and {RKSeal::Commands::Edit}; it lives
+    # in its own file so neither command file owns the other's return type.
+    #
+    # @!attribute [r] secret_name
+    #   @return [String] the Secret name that was sealed.
+    # @!attribute [r] namespace
+    #   @return [String] the namespace it was sealed for.
+    # @!attribute [r] output_path
+    #   @return [String] absolute path of the written `<name>.yaml`.
+    # @!attribute [r] deployed
+    #   @return [Boolean] whether the manifest was applied to the cluster
+    #     (always false for `create`).
+    Result = Data.define(:secret_name, :namespace, :output_path, :deployed)
+  end
+end

data/lib/rkseal/commands/validate.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RKSeal
+  module Commands
+    # Orchestrates the `rkseal validate <namespace> <secret-name>` flow (and its
+    # `--file <path>` variant).
+    #
+    # Asks the controller whether a SealedSecret is well-formed and decryptable
+    # for its target, via `kubeseal --validate`. It does not decrypt or expose
+    # anything; it is a pre-flight check you can run before committing or
+    # applying. No editor, no workspace, no cluster Secret read, no file write.
+    #
+    # Input is either the local `<name>.yaml` in the output directory, or an
+    # explicit file path (`file:`), which takes precedence and lets you validate
+    # any SealedSecret manifest regardless of name.
+    #
+    # @example validate the local <name>.yaml
+    #   RKSeal::Commands::Validate.new(namespace: "app", name: "db").call
+    # @example validate an arbitrary file
+    #   RKSeal::Commands::Validate.new(file: "out/db.yaml").call
+    class Validate
+      # @return [String, nil]
+      attr_reader :namespace
+      # @return [String, nil]
+      attr_reader :name
+      # @return [String, nil] explicit file path to validate, if given.
+      attr_reader :file
+
+      # @param namespace [String, nil] target namespace (positional CLI arg);
+      #   may be nil when `file:` is used.
+      # @param name [String, nil] Secret name (positional CLI arg); the
+      #   `<name>.yaml` stem. May be nil when `file:` is used.
+      # @param file [String, nil] explicit SealedSecret file path; overrides the
+      #   `<name>.yaml` lookup when present.
+      # @param kubeseal [RKSeal::Kubeseal] sealing adapter (validate).
+      # @param output_dir [String] directory the `<name>.yaml` is read from (CWD).
+      def initialize(namespace: nil, name: nil, file: nil,
+                     kubeseal: Kubeseal.new, output_dir: Dir.pwd)
+        @namespace = namespace
+        @name = name
+        @file = file
+        @kubeseal = kubeseal
+        @output_dir = output_dir
+      end
+
+      # Run the validation.
+      #
+      # @return [String] the validated path (so the CLI can name it in the
+      #   "valid" message).
+      # @raise [RKSeal::InvalidInputError] the target file does not exist.
+      # @raise [RKSeal::ValidationError] the controller rejected the SealedSecret
+      #   (the message carries the reason; the CLI prints it and exits non-zero).
+      # @raise [RKSeal::CommandError] the validate operation itself failed.
+      def call
+        @kubeseal.ensure_available!
+        path = target_path
+        @kubeseal.validate(read_sealed(path))
+        path
+      end
+
+      private
+
+      # The file to validate: an explicit --file wins; otherwise <name>.yaml in
+      # the output directory.
+      def target_path
+        return File.expand_path(@file) if @file
+
+        File.expand_path(File.join(@output_dir, "#{@name}.yaml"))
+      end
+
+      def read_sealed(path)
+        File.read(path)
+      rescue SystemCallError => e
+        raise InvalidInputError, "cannot read SealedSecret file #{path.inspect}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/rkseal/commands/view.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RKSeal
+  module Commands
+    # Orchestrates the `rkseal view <namespace> <secret-name>` flow.
+    #
+    # A strictly read-only inspector: it reads the live unsealed Secret from the
+    # cluster (the only source of current values) and renders the full Secret
+    # manifest as a string for the CLI to print. It NEVER opens `$EDITOR`, never
+    # provisions a {RKSeal::SecureWorkspace}, and never writes a file.
+    #
+    # By default `data` is shown as raw base64 (verbatim, consistent with `edit`).
+    # With `reveal: true` the values are decoded and presented as plaintext
+    # `stringData` -- an explicit opt-in for the operator who wants to read the
+    # cleartext.
+    #
+    # If the Secret is absent from the cluster, the flow fails fast and points the
+    # user at `create`.
+    #
+    # @example show base64 (default)
+    #   puts RKSeal::Commands::View.new(namespace: "app", name: "db").call
+    # @example reveal plaintext
+    #   puts RKSeal::Commands::View.new(namespace: "app", name: "db", reveal: true).call
+    class View
+      # @return [String]
+      attr_reader :namespace
+      # @return [String]
+      attr_reader :name
+      # @return [Boolean] whether to decode data to plaintext stringData.
+      attr_reader :reveal
+
+      # @param namespace [String] target namespace (positional CLI arg).
+      # @param name [String] Secret name (positional CLI arg).
+      # @param reveal [Boolean] decode data to plaintext; defaults to false.
+      # @param kubectl [RKSeal::Kubectl] cluster adapter (read only).
+      def initialize(namespace:, name:, reveal: false, kubectl: Kubectl.new)
+        @namespace = namespace
+        @name = name
+        @reveal = reveal
+        @kubectl = kubectl
+      end
+
+      # Run the view flow: read the cluster Secret and render it.
+      #
+      # Side effects: a single read-only `kubectl get secret`. No editor, no
+      # workspace, no file write.
+      #
+      # @return [String] the full Secret manifest YAML to print.
+      # @raise [RKSeal::NotFoundError] the Secret is absent (points at `create`).
+      # @raise [RKSeal::CommandError] kubectl failed.
+      def call
+        @kubectl.ensure_available!
+        secret = Secret.from_kubectl_json(@kubectl.get_secret(name: @name, namespace: @namespace))
+        secret.to_buffer(reveal: @reveal)
+      end
+    end
+  end
+end

data/lib/rkseal/context_guard.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module RKSeal
+  # Gatekeeper for the one genuinely dangerous operation: deploying to a
+  # cluster. Applying a SealedSecret to the wrong context can clobber another
+  # environment, so a deploy must be explicitly confirmed by the operator.
+  #
+  # rkseal always operates on the *current* kube context -- there is no
+  # allow-list. The guard's job is narrow: surface the active context and ask
+  # the operator to confirm before {RKSeal::Kubectl#apply} runs. Deploy is never
+  # the default for `edit`; this class enforces the "explicit + confirmed"
+  # requirement via an interactive yes/no prompt that defaults to No.
+  #
+  # This class does NOT shell out itself -- it delegates to the injected
+  # {RKSeal::Kubectl} for the context name and to a Thor shell for the prompt.
+  class ContextGuard
+    # @param kubectl [RKSeal::Kubectl] adapter used to read the active context.
+    # @param prompt [Thor::Shell::Basic] shell used for the interactive
+    #   confirmation; injected so specs can drive #yes? without real stdin.
+    def initialize(kubectl:, prompt: Thor::Shell::Basic.new)
+      @kubectl = kubectl
+      @prompt = prompt
+    end
+
+    # The current kube context, as reported by kubectl.
+    #
+    # @return [String]
+    # @raise [RKSeal::CommandError] if kubectl cannot report a context.
+    def current_context
+      @kubectl.current_context
+    end
+
+    # Surface the active context and ask the operator to confirm the deploy.
+    # Called immediately before {RKSeal::Kubectl#apply}; the apply happens only
+    # when this returns true. The prompt defaults to No, so an empty answer (or a
+    # non-interactive run) declines.
+    #
+    # @param secret_name [String] the SealedSecret's name, for the prompt.
+    # @param namespace [String] the target namespace, for the prompt.
+    # @return [Boolean] whether the operator approved the deploy.
+    # @raise [RKSeal::CommandError] if kubectl cannot report a context.
+    #
+    # rubocop:disable Naming/PredicateMethod -- this is an action ("ask and
+    # apply-or-not"), not a query; its name is a frozen part of the public API
+    # that the command layer codes against, so it cannot take a `?` suffix.
+    def confirm_deploy(secret_name:, namespace:)
+      context = current_context
+      @prompt.yes?(
+        "Deploy #{secret_name.inspect} (namespace #{namespace.inspect}) " \
+        "to context #{context.inspect}? [y/N]"
+      )
+    end
+    # rubocop:enable Naming/PredicateMethod
+  end
+end

data/lib/rkseal/editor.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module RKSeal
+  # Launches the user's `$EDITOR` on a buffer and returns the edited content.
+  #
+  # The editor never sees a persistent path: the caller supplies a RAM-backed
+  # path from {RKSeal::SecureWorkspace}, this class seeds it with the initial
+  # content, spawns `$EDITOR <path>`, blocks until the editor exits, then reads
+  # the result back. It does not create, choose, or destroy the path -- that is
+  # the workspace's job -- which keeps the "never on disk" guarantee in one
+  # place.
+  class Editor
+    # Environment variables consulted, in priority order, to find the editor
+    # command when none is injected explicitly.
+    ENV_KEYS = %w[VISUAL EDITOR].freeze
+
+    # vim-family editors persist buffer contents to files OUTSIDE the RAM-backed
+    # path -- a swap file and the viminfo register/mark history -- which would
+    # leak plaintext to persistent disk despite the workspace guarantee. Each
+    # flag below suppresses one such sink (`-n` disables the swap file; `-i NONE`
+    # disables viminfo). Keyed by the flag we test for, so an operator who has
+    # already set it keeps their choice (we never duplicate it).
+    VIM_HARDENING = { "-n" => ["-n"], "-i" => ["-i", "NONE"] }.freeze
+
+    # @param command [String, nil] explicit editor command; when nil it is
+    #   resolved from {ENV_KEYS} at edit time.
+    def initialize(command: nil)
+      @command = command
+    end
+
+    # Seed `path` with `content`, open it in `$EDITOR`, wait for the editor to
+    # exit, and return the (possibly modified) file contents.
+    #
+    # Side effects: writes `content` to `path` and re-reads it; spawns and waits
+    # on the editor process. Does not delete `path`.
+    #
+    # @param content [String] initial buffer contents (e.g. a seed manifest).
+    # @param path [String] RAM-backed file path to edit on
+    #   (from {RKSeal::SecureWorkspace}).
+    # @return [String] the buffer contents after the editor exits.
+    # @raise [RKSeal::EditorError] if no editor is configured, the editor cannot
+    #   be launched, or it exits signaling the user aborted.
+    def edit(content:, path:)
+      # Resolve BEFORE writing any secret: if no editor is available we must
+      # fail fast, before the plaintext ever lands in the buffer.
+      argv = editor_argv
+
+      File.write(path, content)
+      launch(argv, path)
+      File.read(path)
+    end
+
+    # Resolve the editor command that would be used (injected value or the first
+    # set variable among {ENV_KEYS}). Exposed so a flow can fail fast *before*
+    # provisioning a workspace if no editor is available.
+    #
+    # @return [String] the resolved editor command.
+    # @raise [RKSeal::EditorError] if none is set.
+    def resolve_command
+      candidate = @command || env_command
+      if candidate.nil? || candidate.strip.empty?
+        raise EditorError,
+              "no editor configured: set $VISUAL or $EDITOR (e.g. `export EDITOR=vim`)"
+      end
+
+      candidate
+    end
+
+    private
+
+    attr_reader :command
+
+    # First non-empty value among {ENV_KEYS}, honouring their priority order.
+    def env_command
+      ENV_KEYS.filter_map { |key| ENV.fetch(key, nil) }.find { |value| !value.strip.empty? }
+    end
+
+    # Split the resolved command into an argv array so editors carrying flags
+    # (`code --wait`, `subl -w`, `emacsclient -nw`) launch correctly without a
+    # shell. The file path is appended as a separate, un-split element so a path
+    # is never re-parsed for metacharacters.
+    #
+    # @return [Array<String>] the editor command split into argv tokens.
+    # @raise [RKSeal::EditorError] if the command does not resolve to any token.
+    def editor_argv
+      tokens = Shellwords.split(resolve_command)
+      raise EditorError, "editor command resolved to nothing" if tokens.empty?
+
+      harden_side_files(tokens)
+    end
+
+    # For the vim family, inject the flags from {VIM_HARDENING} the operator has
+    # not already set, so swap/viminfo never write the plaintext to disk. The
+    # flags go right after the command and before any user arguments (and the
+    # path, appended in {#launch}), which is where vim expects its options.
+    # Other editors pass through untouched.
+    def harden_side_files(tokens)
+      command, *rest = tokens
+      return tokens unless vim_family?(command)
+
+      flags = VIM_HARDENING.except(*rest).values.flatten
+      [command, *flags, *rest]
+    end
+
+    # Whether the editor binary is a vim variant (vim, vi, nvim, gvim, mvim, and
+    # suffixed builds like vim.basic/vimx). Matched on the basename so a full
+    # path still resolves.
+    def vim_family?(command)
+      name = File.basename(command)
+      name.start_with?("vim", "nvim") || %w[vi gvim mvim].include?(name)
+    end
+
+    # Spawn the editor (no shell), wait for it, and translate any non-clean exit
+    # into an {EditorError}. A non-zero status or a termination by signal both
+    # mean "the user did not save a usable result" -- we treat them as aborts.
+    def launch(argv, path)
+      pid = Process.spawn(*argv, path)
+      _, status = Process.wait2(pid)
+      raise_on_failure(status, argv.first)
+    rescue Errno::ENOENT
+      raise EditorError, "could not launch editor: command not found (#{argv.first.inspect})"
+    rescue SystemCallError => e
+      raise EditorError, "could not launch editor #{argv.first.inspect}: #{e.message}"
+    end
+
+    def raise_on_failure(status, command_name)
+      return if status.success?
+
+      if status.signaled?
+        raise EditorError,
+              "editor #{command_name.inspect} was killed by signal #{status.termsig}; aborting"
+      end
+
+      raise EditorError,
+            "editor #{command_name.inspect} exited with status #{status.exitstatus}; " \
+            "treating as aborted edit"
+    end
+  end
+end

data/lib/rkseal/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RKSeal
+  # Error hierarchy for rkseal's fail-fast behavior.
+  #
+  # Every error rkseal raises on purpose descends from {RKSeal::Error}, so the
+  # CLI entry point can rescue that one base class, print a single clean line,
+  # and exit non-zero -- without swallowing genuinely unexpected exceptions
+  # (those bubble up with a backtrace, as they should).
+  #
+  # Guidelines for raisers:
+  # - Pick the most specific subclass that fits.
+  # - Put a human-actionable message in the exception (what went wrong + what to
+  #   do about it). Never put secret *values* in a message.
+  # - Do not rescue-and-wrap unless you are adding context; prefer to let a
+  #   specific error propagate.
+
+  # Base class for all errors deliberately raised by rkseal.
+  class Error < StandardError; end
+
+  # A required external binary (`kubeseal` or `kubectl`) was not found on PATH,
+  # or is not executable. Message should name the missing tool.
+  class DependencyMissingError < Error; end
+
+  # An external command ran but exited non-zero. Carries the command label,
+  # exit status, and captured stderr so callers can surface a useful message
+  # without re-deriving them.
+  class CommandError < Error
+    # @return [String] human label for the command (e.g. "kubeseal seal").
+    attr_reader :command
+    # @return [Integer, nil] process exit status, if one was produced.
+    attr_reader :status
+    # @return [String, nil] captured stderr (already scrubbed of secrets).
+    attr_reader :stderr
+
+    # @param message [String] human-readable summary.
+    # @param command [String, nil] command label.
+    # @param status [Integer, nil] exit status.
+    # @param stderr [String, nil] captured stderr.
+    def initialize(message = nil, command: nil, status: nil, stderr: nil)
+      @command = command
+      @status = status
+      @stderr = stderr
+      super(message)
+    end
+  end
+
+  # The thing the user asked to operate on does not exist where it must.
+  # Notably: `edit` was asked for a Secret that is absent from the cluster
+  # (the message must point the user at `rkseal create`).
+  class NotFoundError < Error; end
+
+  # The user's input is unusable: an empty edit buffer, malformed YAML from the
+  # editor, a manifest that is not a valid Kubernetes Secret, an unknown scope,
+  # a `--from-file` path that does not exist, etc.
+  class InvalidInputError < Error; end
+
+  # A SealedSecret was checked against the controller and cannot be decrypted
+  # (`kubeseal --validate` rejected it -- e.g. wrong scope, tampered ciphertext,
+  # or sealed for a different name/namespace). Distinct from {CommandError},
+  # which covers operational failures (missing binary, unreachable cluster) that
+  # say nothing about the SealedSecret's validity. The message carries the
+  # controller's stated reason.
+  class ValidationError < Error; end
+
+  # Something went wrong provisioning, mounting, or tearing down the RAM-backed
+  # workspace (see {RKSeal::SecureWorkspace}). Treated as fatal: rkseal must not
+  # silently fall back to on-disk scratch space.
+  class WorkspaceError < Error; end
+
+  # `$EDITOR` is unset/blank, could not be launched, or exited in a way that
+  # signals the user aborted the edit.
+  class EditorError < Error; end
+end