rkseal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ebc10a4204a042490b3ad908bed3d1cfd625ee03743f21f147f1d80b21fb306f
+  data.tar.gz: ba5ffd88f83075193e57357edadfd0539f64e9587b76664d8f1fd0c2a89b95b0
+SHA512:
+  metadata.gz: 04d897666453e1e63e870c0c4c31f5dc8adb2a00d4b7167b5859c5f3adb0e73366fad81d6be29843d7e35ed44fc365f793529d45161cead4857800bea963bcbc
+  data.tar.gz: 56ff59be8191ec4c27d612422766f174f92d393417f8d3e47f6a8185d26feccde71bea6da8353a5e511c15f4e140a7ed7bea2bb894f7da213e2bfcfd752f5533

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piotr Wojcieszonek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# rkseal
+
+Interactively create and edit Kubernetes [SealedSecrets](https://github.com/bitnami-labs/sealed-secrets)
+from your terminal, in the spirit of `knife vault create/edit`.
+
+`rkseal` wraps the `kubeseal` CLI. You edit a **full Kubernetes Secret manifest** in
+`$EDITOR`; `rkseal` seals it with the controller's public key and writes the resulting
+`SealedSecret` to the current directory. The plaintext buffer lives only on a RAM-backed
+path and is destroyed when you are done — it never touches persistent disk.
+
+## Commands
+
+```sh
+rkseal create    <namespace> <secret-name>   # author a new sealed secret
+rkseal edit      <namespace> <secret-name>   # edit an existing one
+rkseal reencrypt <namespace> <secret-name>   # rotate to the controller's newest key
+rkseal validate  <namespace> <secret-name>   # check a SealedSecret with the controller
+rkseal view      <namespace> <secret-name>   # print the live Secret (read-only)
+rkseal list      [namespace]                 # list SealedSecrets (metadata only)
+rkseal version                               # print the installed rkseal version
+```
+
+- `create` opens an empty, commented Secret template for you to fill in.
+- `edit` reads the **live** unsealed Secret from the cluster
+  (`kubectl get secret … -o json`) — the only way to recover current values — opens it for
+  editing, then re-seals. If the Secret is absent from the cluster but a local
+  `<secret-name>.yaml` exists (e.g. you ran `create` but never deployed), `rkseal` switches
+  **automatically to an offline local edit** (see [`edit --local`](#edit---local-offline)).
+  Only if **neither** the cluster Secret nor a local file exists does it fail fast and point
+  you at `create`.
+- `reencrypt` rotates an existing SealedSecret onto the controller's current sealing key
+  (`kubeseal --re-encrypt`) without exposing plaintext. It reads the local
+  `<secret-name>.yaml` if present, otherwise the live SealedSecret; if neither exists it
+  points you at `create`. The result is written back to `<secret-name>.yaml`.
+- `validate` asks the controller whether a SealedSecret is well-formed and decryptable for
+  its target (`kubeseal --validate`) — a safe pre-flight check. It validates the local
+  `<secret-name>.yaml`, or any file via `--file <path>`. Prints `valid` and exits 0, or
+  prints the reason and exits non-zero.
+- `view` prints the live unsealed Secret manifest to **STDOUT, read-only** — no editor, no
+  RAM workspace, no file written.
+- `list` prints a table of the SealedSecret objects in the cluster (columns **NAMESPACE,
+  NAME, SCOPE, AGE**). Give a `[namespace]` to scope it to one namespace; omit it to list all.
+  **Read-only and metadata-only** — it never prints encrypted data (not even the data keys).
+- `create`, `edit`, and `reencrypt` write `<secret-name>.yaml` into the current working
+  directory. `edit` and `reencrypt` can deploy with `kubectl apply`, but **only** with an
+  explicit opt-in flag, and only after confirming the active kube context.
+
+In the `edit` buffer, `data:` values are shown as **base64, verbatim** — they are never
+decoded to plaintext. To change a value readably, add it under a `stringData:` block; on
+save it is folded into `data` (and wins per key). The seeded buffer includes a worked
+example to make this obvious. Pass `--string-data` to decode the **whole** buffer to plaintext
+`stringData` up front (an opt-in plaintext exposure).
+
+### `edit` flags & behaviour
+
+- `--scope strict|namespace-wide|cluster-wide` — by default `edit` **preserves the existing
+  scope**: it reads the SealedSecret's scope annotation from the cluster, falling back to the
+  local `<secret-name>.yaml`, then to `strict`. Pass `--scope` to override.
+- `--deploy` — after writing, `kubectl apply` the result. Surfaces the active kube context
+  and asks you to confirm first. Never the default.
+- `--yes` — skip the interactive deploy confirmation (only meaningful together with
+  `--deploy`), for non-interactive pipelines.
+- `--local` — force the offline local edit without contacting the cluster at all (see below).
+- `--string-data` — decode the live Secret's `data` into plaintext `stringData` for editing,
+  instead of showing it as raw base64.
+- `--cert`, `--controller-name`, `--controller-namespace`, `--refresh-cert` — control which
+  controller certificate is used to re-seal (same as `create`).
+- **No-op short-circuit:** if you save the buffer without changing anything, `rkseal` writes
+  no file (re-sealing identical input would only produce a spurious ciphertext diff). Because
+  nothing new is produced, a `--deploy` on an unchanged secret deploys **nothing**.
+
+#### `edit --local` (offline)
+
+When a SealedSecret was authored with `create` but **never deployed**, there is no unsealed
+Secret in the cluster to recover values from. `rkseal` then edits the local
+`<secret-name>.yaml` **offline** — reached automatically when the cluster Secret is absent
+but the local file exists, or forced with `--local` (which never contacts the cluster, useful
+when it is unreachable).
+
+Because a SealedSecret cannot be decrypted, every existing key is shown as `<redacted>`:
+
+- **leave it `<redacted>`** — the existing ciphertext is kept byte-for-byte (no re-seal),
+- **replace the value** (or add a new key) — that key is re-sealed and merged in,
+- **delete the line** — that key is removed.
+
+Scope is **fixed** in this mode (`--scope` is rejected) and `name`/`namespace` cannot change —
+kept ciphertext binds them and cannot be re-sealed without its plaintext. The automatic
+fallback fires only on a definitive "not found"; an **unreachable** cluster surfaces as an
+error instead (use `--local` to force offline). `--deploy` / `--yes` behave exactly as for the
+online `edit`.
+
+### `create` flags
+
+- `--scope`, `--type`, `--cert`, `--controller-name`, `--controller-namespace`.
+- `--from-file key=path` (repeatable) — pre-seed a value from a file (binary-safe, stored as
+  base64) before the editor opens.
+- `--no-edit` — seal the pre-seeded Secret directly, without opening `$EDITOR` (handy for
+  TLS / dockerconfig / binary payloads).
+- `--string-data` — seed the buffer with a plaintext `stringData` block instead of base64
+  `data`, so you type values in clear (folded into `data` on save).
+- `--refresh-cert` — bypass the cached controller cert and re-fetch it for this run.
+- The controller certificate is resolved up front, so an unreachable controller fails fast
+  **before** you start editing.
+
+### `reencrypt` flags
+
+- `--deploy` / `--yes` — same deploy semantics as `edit` (opt-in, context-confirmed; `--yes`
+  skips the prompt).
+- `--cert`, `--controller-name`, `--controller-namespace`, `--refresh-cert`.
+
+### `validate` flags
+
+- `--file <path>` — validate an arbitrary SealedSecret manifest instead of the local
+  `<secret-name>.yaml` (then `NAMESPACE`/`NAME` are optional).
+- `--cert`, `--controller-name`, `--controller-namespace`, `--refresh-cert`.
+
+### `view` flags
+
+- `--reveal` — decode `data` and print values as plaintext `stringData` (default shows raw
+  base64, consistent with `edit`). Read-only: `view` never writes a file or opens an editor.
+
+### `--refresh-cert`
+
+`create`, `edit`, `reencrypt`, and `validate` accept `--refresh-cert` to bypass the cached
+controller certificate and re-fetch it from the live controller for that run.
+
+## Requirements
+
+- Ruby **4.0.2** (managed with `rvm` + a dedicated `rkseal` gemset).
+- `kubeseal` (developed against **v0.36.6**) and `kubectl` on your `PATH`.
+- Access to a cluster running the sealed-secrets controller (for `--fetch-cert`, `edit`,
+  and deploys).
+
+## Development
+
+```sh
+rvm use 4.0.2@rkseal --create   # isolated gemset — never install gems globally
+bundle install
+bundle exec rspec               # unit suite (adapters stubbed; no cluster needed)
+bundle exec rubocop             # lint
+bundle exec exe/rkseal create my-namespace my-secret
+```
+
+Unit tests stub the `kubeseal` / `kubectl` / `$EDITOR` adapters, so the suite runs without
+a cluster. Real cluster operations are reserved for explicit integration tests gated on the
+`docker-desktop` context.
+
+## Security model
+
+- **Plaintext never hits persistent disk.** The edit buffer is RAM-backed
+  (`tmpfs`/`/dev/shm` on Linux, an ephemeral `hdiutil` RAM disk on macOS) and is shredded
+  and torn down on exit, including on error or signal.
+- **Deploys confirm the active context.** Applying to the wrong cluster is the dangerous
+  operation, so deploy is never the default: `rkseal` surfaces the current kube context and
+  asks you to confirm before `kubectl apply`. There is no in-code allow-list — `rkseal` uses
+  whatever context is active — so switch context deliberately before deploying (`--yes`
+  bypasses only the prompt, not the `--deploy` opt-in).
+- **Names are validated at the boundary.** `<namespace>` and `<secret-name>` must be valid
+  Kubernetes DNS-1123 names; anything else (path traversal like `../`, a leading `-` that
+  could be read as a `kubectl`/`kubeseal` flag, `/`, uppercase, …) is rejected up front,
+  before any editor, cluster call, or file write.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/exe/rkseal

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rkseal"
+
+# Thin entry point: hand the raw ARGV to the Thor CLI and translate the gem's
+# fail-fast errors into a clean non-zero exit with a single-line message, rather
+# than dumping a Ruby backtrace on the user. Implementation lives in RKSeal::CLI.
+RKSeal::CLI.dispatch(ARGV)

data/lib/rkseal/cli.rb

@@ -0,0 +1,471 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module RKSeal
+  # Thor-based command-line interface: parses ARGV, validates options, and
+  # dispatches to the orchestration commands. It is intentionally thin -- it
+  # maps flags/positionals onto {RKSeal::Commands::Create} /
+  # {RKSeal::Commands::Edit}, prints their {RKSeal::Commands::Result}, and turns
+  # the gem's fail-fast {RKSeal::Error}s into a single clean line + non-zero
+  # exit. No business logic lives here.
+  #
+  # rubocop:disable Metrics/ClassLength -- length here is Thor's declarative
+  # `method_option` surface (every flag for both subcommands plus their
+  # long_desc help text), not logic. The two command bodies stay thin and
+  # delegate straight to the orchestration classes.
+  class CLI < Thor
+    # kubeseal's `--scope` strings, as exposed on the CLI, mapped to the symbols
+    # the command/adapter layers expect. Thor does not underscore enum values.
+    SCOPE_SYMBOLS = {
+      "strict" => :strict,
+      "namespace-wide" => :namespace_wide,
+      "cluster-wide" => :cluster_wide
+    }.freeze
+
+    # Make argument/usage errors (and our rescued errors) exit non-zero rather
+    # than return 0, so the CLI is shell-script friendly.
+    def self.exit_on_failure?
+      true
+    end
+
+    class << self
+      # `dispatch` is also Thor's own internal 4-arg command router, which
+      # {Thor.start} calls. Preserve it under an alias so our public 1-arg entry
+      # point can reuse the name (as the gem's contract requires) without
+      # clobbering Thor's routing.
+      alias thor_dispatch dispatch
+
+      # Entry point used by `exe/rkseal`, and Thor's internal command router.
+      #
+      # Dual-role on arity:
+      #   - called as `dispatch(argv)` (a single Array, from `exe/rkseal`): run
+      #     {Thor.start} and translate any deliberately-raised {RKSeal::Error}
+      #     into a one-line stderr message with a non-zero exit -- no backtrace.
+      #     Thor's own parse errors keep their {exit_on_failure?} handling;
+      #     unexpected exceptions propagate.
+      #   - called by Thor internally (`dispatch(meth, args, opts, config)`):
+      #     delegate to Thor's preserved router unchanged.
+      #
+      # @param args [Array] either `[argv]` (public) or Thor's four router args.
+      # @return [void]
+      def dispatch(*args)
+        return thor_dispatch(*args) unless args.length == 1 && args.first.is_a?(Array)
+
+        begin
+          start(args.first)
+        rescue RKSeal::Error => e
+          warn(e.message)
+          exit(1)
+        end
+      end
+    end
+
+    desc "create NAMESPACE NAME", "Author a new SealedSecret and write <NAME>.yaml"
+    long_desc <<~LONGDESC
+      Opens an empty, commented Kubernetes Secret manifest in $EDITOR on a
+      RAM-backed buffer. After you save, the Secret is sealed with the
+      controller's public key and written as <NAME>.yaml in the current
+      directory. The plaintext buffer never touches persistent disk.
+
+      Pre-seed values with --from-file key=path (repeatable; binary-safe, stored
+      as base64). Pass --no-edit to seal the pre-seeded Secret directly without
+      opening an editor (useful for TLS/dockerconfig/binary payloads).
+    LONGDESC
+    method_option :scope, type: :string, default: "strict",
+                          enum: %w[strict namespace-wide cluster-wide],
+                          desc: "Sealing scope bound into the ciphertext"
+    method_option :type, type: :string, default: Secret::DEFAULT_TYPE,
+                         desc: "Secret type (e.g. Opaque, kubernetes.io/tls)"
+    method_option :cert, type: :string,
+                         desc: "Controller certificate (file or URL); else --fetch-cert/env is used"
+    method_option :"controller-name", type: :string,
+                                      desc: "sealed-secrets controller name"
+    method_option :"controller-namespace", type: :string,
+                                           desc: "controller namespace"
+    method_option :"refresh-cert", type: :boolean, default: false,
+                                   desc: "Bypass the cert cache and re-fetch from the controller"
+    method_option :"from-file", type: :array,
+                                desc: "Pre-seed key=path value(s) into the buffer before editing"
+    method_option :"no-edit", type: :boolean, default: false,
+                              desc: "Seal the pre-seeded Secret directly, without opening $EDITOR"
+    method_option :"string-data", type: :boolean, default: false,
+                                  desc: "Edit values as plaintext stringData instead of base64 data"
+    # Author a new SealedSecret.
+    #
+    # @param namespace [String] target namespace.
+    # @param name [String] Secret name (also the output filename stem).
+    # @return [void]
+    def create(namespace, name)
+      validate_identifiers!(namespace, name)
+      result = Commands::Create.new(
+        namespace: namespace, name: name,
+        scope: scope_symbol, type: options["type"],
+        from_file: parsed_from_file, no_edit: options["no-edit"],
+        string_data: options["string-data"],
+        kubeseal: build_kubeseal
+      ).call
+      report(result)
+    end
+
+    desc "edit NAMESPACE NAME", "Edit an existing SealedSecret and write <NAME>.yaml"
+    long_desc <<~LONGDESC
+      Reads the live unsealed Secret from the cluster (kubectl get secret -o
+      json) -- the only way to recover current values -- and opens it in $EDITOR
+      on a RAM-backed buffer, with `data` shown as base64 (verbatim, not decoded
+      to plaintext). Add plaintext under `stringData` to change values readably.
+      After you save, it re-seals and writes <NAME>.yaml in the current
+      directory.
+
+      If the Secret is absent from the cluster but a local <NAME>.yaml exists
+      (e.g. you ran `create` but never deployed), rkseal switches automatically
+      to an OFFLINE local edit -- no flag needed. There the existing values
+      cannot be decrypted, so each key is shown as <redacted>: leave it to keep
+      the sealed value, replace it to re-seal that key, add lines for new keys,
+      or delete lines to remove keys. Scope is fixed (cannot be changed offline).
+      If neither the cluster Secret nor a local file exists, rkseal fails fast
+      and points you at `create`.
+
+      Pass --local to force the offline path without contacting the cluster at
+      all (useful when the cluster is unreachable). The automatic fallback only
+      fires on a definitive "not found"; an unreachable cluster is surfaced as an
+      error instead, since rkseal cannot then tell whether the secret exists
+      remotely.
+
+      Scope is preserved automatically: rkseal reads the existing SealedSecret's
+      scope annotation from the cluster (falling back to the local <NAME>.yaml,
+      then to strict). Pass --scope to override (cluster edits only; an offline
+      edit cannot change scope).
+
+      If you save without changing anything, rkseal writes no file -- and because
+      there is nothing new to apply, a --deploy on an unchanged secret is a no-op
+      (nothing is deployed).
+
+      Deploy is opt-in only: pass --deploy to `kubectl apply` the result, which
+      first surfaces the active kube context and asks you to confirm. In a
+      non-interactive pipeline, add --yes to skip the prompt (still requires
+      --deploy).
+    LONGDESC
+    method_option :scope, type: :string,
+                          enum: %w[strict namespace-wide cluster-wide],
+                          desc: "Sealing scope (overrides the secret's existing scope)"
+    method_option :local, type: :boolean, default: false,
+                          desc: "Force offline edit of the local file (auto-detected otherwise)"
+    method_option :"string-data", type: :boolean, default: false,
+                                  desc: "Edit values as plaintext stringData instead of base64 data"
+    method_option :deploy, type: :boolean, default: false,
+                           desc: "Apply the result to the cluster after writing (opt-in)"
+    method_option :yes, type: :boolean, default: false,
+                        desc: "Skip the deploy confirmation prompt (only with --deploy)"
+    method_option :cert, type: :string,
+                         desc: "Controller certificate (file or URL); else --fetch-cert/env is used"
+    method_option :"controller-name", type: :string,
+                                      desc: "sealed-secrets controller name"
+    method_option :"controller-namespace", type: :string,
+                                           desc: "controller namespace"
+    method_option :"refresh-cert", type: :boolean, default: false,
+                                   desc: "Bypass the cert cache and re-fetch from the controller"
+    # Edit an existing SealedSecret. Reads current values from the cluster; if
+    # the Secret is absent there but a local <NAME>.yaml exists, automatically
+    # falls back to the offline local edit. `--local` forces the offline path.
+    #
+    # @param namespace [String] target namespace.
+    # @param name [String] Secret name (also the output filename stem).
+    # @return [void]
+    def edit(namespace, name)
+      validate_identifiers!(namespace, name)
+      result = options["local"] ? edit_local(namespace, name) : edit_auto(namespace, name)
+      report(result)
+    end
+
+    desc "reencrypt NAMESPACE NAME", "Re-encrypt a SealedSecret to the controller's newest key"
+    long_desc <<~LONGDESC
+      Rotates an existing SealedSecret onto the controller's current sealing key
+      (`kubeseal --re-encrypt`) without ever exposing plaintext. The input is the
+      SealedSecret itself: rkseal reads the local <NAME>.yaml if present,
+      otherwise the live SealedSecret from the cluster. If neither exists, it
+      fails fast and points you at `create`. The result is written back to
+      <NAME>.yaml.
+
+      Deploy works exactly like `edit`: pass --deploy to `kubectl apply`, which
+      surfaces the active context and asks you to confirm (--yes skips the prompt
+      in non-interactive pipelines).
+    LONGDESC
+    method_option :deploy, type: :boolean, default: false,
+                           desc: "Apply the result to the cluster after writing (opt-in)"
+    method_option :yes, type: :boolean, default: false,
+                        desc: "Skip the deploy confirmation prompt (only with --deploy)"
+    method_option :cert, type: :string,
+                         desc: "Controller certificate (file or URL); else --fetch-cert/env is used"
+    method_option :"controller-name", type: :string,
+                                      desc: "sealed-secrets controller name"
+    method_option :"controller-namespace", type: :string,
+                                           desc: "controller namespace"
+    method_option :"refresh-cert", type: :boolean, default: false,
+                                   desc: "Bypass the cert cache and re-fetch from the controller"
+    # Re-encrypt an existing SealedSecret to the newest controller key.
+    #
+    # @param namespace [String] target namespace.
+    # @param name [String] Secret name (also the output filename stem).
+    # @return [void]
+    def reencrypt(namespace, name)
+      validate_identifiers!(namespace, name)
+      result = Commands::Reencrypt.new(
+        namespace: namespace, name: name,
+        deploy: options["deploy"], assume_yes: options["yes"],
+        kubectl: Kubectl.new, kubeseal: build_kubeseal
+      ).call
+      report(result)
+    end
+
+    desc "validate [NAMESPACE NAME]", "Check a SealedSecret with the controller"
+    long_desc <<~LONGDESC
+      Asks the controller whether a SealedSecret is well-formed and decryptable
+      for its target (`kubeseal --validate`). Nothing is decrypted or revealed --
+      it is a safe pre-flight check before you commit or apply.
+
+      By default it validates the local <NAME>.yaml for the given namespace/name.
+      Pass --file <path> to validate an arbitrary SealedSecret manifest instead
+      (NAMESPACE/NAME are then optional). On success it prints a "valid" line and
+      exits 0; if the controller rejects the secret, it prints the reason and
+      exits non-zero.
+    LONGDESC
+    method_option :file, type: :string,
+                         desc: "Validate this SealedSecret file instead of <NAME>.yaml"
+    method_option :cert, type: :string,
+                         desc: "Controller certificate (file or URL); else --fetch-cert/env is used"
+    method_option :"controller-name", type: :string,
+                                      desc: "sealed-secrets controller name"
+    method_option :"controller-namespace", type: :string,
+                                           desc: "controller namespace"
+    method_option :"refresh-cert", type: :boolean, default: false,
+                                   desc: "Bypass the cert cache and re-fetch from the controller"
+    # Validate a SealedSecret (local <NAME>.yaml, or --file <path>).
+    #
+    # @param namespace [String, nil] target namespace (omit with --file).
+    # @param name [String, nil] Secret name (omit with --file).
+    # @return [void]
+    def validate(namespace = nil, name = nil)
+      file = options["file"]
+      raise InvalidInputError, "give NAMESPACE NAME or --file <path>" if file.nil? && name.nil?
+
+      validate_identifiers!(namespace, name) unless file
+      path = Commands::Validate.new(
+        namespace: namespace, name: name, file: file, kubeseal: build_kubeseal
+      ).call
+      say("SealedSecret #{path} is valid.")
+    end
+
+    desc "view NAMESPACE NAME", "Print the live Secret for a SealedSecret (read-only)"
+    long_desc <<~LONGDESC
+      Reads the live unsealed Secret from the cluster and prints the full Secret
+      manifest to STDOUT. Strictly read-only: no editor, no RAM workspace, no
+      file is written.
+
+      By default `data` is shown as raw base64 (verbatim, like `edit`). Pass
+      --reveal to decode the values and print them as plaintext `stringData`.
+      If the Secret is not present in the cluster, rkseal fails fast and points
+      you at `create`.
+    LONGDESC
+    method_option :reveal, type: :boolean, default: false,
+                           desc: "Decode data and show values as plaintext stringData"
+    # Print the live Secret for a SealedSecret (read-only).
+    #
+    # @param namespace [String] target namespace.
+    # @param name [String] Secret name.
+    # @return [void]
+    def view(namespace, name)
+      validate_identifiers!(namespace, name)
+      manifest = Commands::View.new(
+        namespace: namespace, name: name, reveal: options["reveal"], kubectl: Kubectl.new
+      ).call
+      say(manifest)
+    end
+
+    desc "list [NAMESPACE]", "List SealedSecrets (metadata only, read-only)"
+    long_desc <<~LONGDESC
+      Lists the SealedSecret objects in the cluster as a table with columns
+      NAMESPACE, NAME, SCOPE, and AGE. Give a NAMESPACE to scope the listing to
+      one namespace; omit it to list across all namespaces.
+
+      Read-only and metadata-only: rkseal prints only each object's
+      name/namespace/scope/age -- never any encrypted data. No editor, no file is
+      written.
+    LONGDESC
+    # List SealedSecrets (read-only, metadata only).
+    #
+    # @param namespace [String, nil] limit to this namespace; omit for all.
+    # @return [void]
+    def list(namespace = nil)
+      Secret.validate_identifier!(field: "namespace", value: namespace) if namespace
+      say(Commands::List.new(namespace: namespace, kubectl: Kubectl.new).call)
+    end
+
+    desc "version", "Print the rkseal version"
+    long_desc "Print the installed rkseal gem version and exit."
+    # @return [void]
+    def version
+      say("rkseal #{RKSeal::VERSION}")
+    end
+
+    private
+
+    # The default `edit`. The local <NAME>.yaml is the working copy: when it is
+    # absent from the cluster or carries un-deployed changes (its sealed payload
+    # differs from the deployed SealedSecret), editing continues on it offline so
+    # those changes are never silently discarded. Otherwise -- no local file, or
+    # it matches what is deployed -- rkseal seeds the editor from the live cluster
+    # Secret (the only way to show decrypted values). After a deploy the file
+    # matches the cluster again, so full values come back. An unreachable cluster
+    # is surfaced as an error (not silently taken offline); use --local to force
+    # offline then.
+    def edit_auto(namespace, name)
+      if local_manifest?(name) && (reason = offline_reason(namespace, name))
+        say(reason)
+        return edit_local(namespace, name)
+      end
+
+      edit_cluster(namespace, name)
+    rescue NotFoundError
+      raise unless local_manifest?(name)
+
+      say("Secret not found in the cluster; editing the local #{name}.yaml offline.")
+      edit_local(namespace, name)
+    end
+
+    # When a local <NAME>.yaml exists, decide whether to edit it offline rather
+    # than seed from the cluster. Returns the message to print when going offline
+    # (the file is absent from the cluster, or diverges from the deployed
+    # SealedSecret), or nil to seed from the cluster. A `NotFound` cluster
+    # SealedSecret means it was never deployed -> offline; other kubectl errors
+    # (e.g. unreachable) propagate.
+    def offline_reason(namespace, name)
+      cluster = Kubectl.new.get_sealedsecret(name: name, namespace: namespace)
+      return nil unless SealedSecret.diverged?(read_local_manifest(name), cluster)
+
+      "Local #{name}.yaml has changes not deployed to the cluster; editing it offline " \
+        "(values shown as <redacted> -- a SealedSecret cannot be decrypted). " \
+        "Deploy to make the cluster authoritative again."
+    rescue NotFoundError
+      "#{name} is not deployed to the cluster; editing the local #{name}.yaml offline."
+    end
+
+    # Recover current values from the live cluster Secret and re-seal.
+    def edit_cluster(namespace, name)
+      Commands::Edit.new(
+        namespace: namespace, name: name,
+        scope: scope_symbol, deploy: options["deploy"], assume_yes: options["yes"],
+        string_data: options["string-data"],
+        kubectl: Kubectl.new, kubeseal: build_kubeseal
+      ).call
+    end
+
+    # The offline local edit: operate on the local <NAME>.yaml. Scope cannot be
+    # overridden -- kept ciphertext cannot be re-sealed under a new scope.
+    def edit_local(namespace, name)
+      if options["scope"]
+        raise InvalidInputError,
+              "scope cannot be changed when editing a local-only SealedSecret " \
+              "(kept values cannot be re-sealed under a new scope)"
+      end
+
+      Commands::EditLocal.new(
+        namespace: namespace, name: name,
+        deploy: options["deploy"], assume_yes: options["yes"],
+        string_data: options["string-data"],
+        kubectl: Kubectl.new, kubeseal: build_kubeseal
+      ).call
+    end
+
+    # Whether a local <NAME>.yaml exists in the working directory (the same path
+    # the commands read/write), making an offline fallback possible.
+    def local_manifest?(name)
+      File.file?(manifest_path(name))
+    end
+
+    # Read the local <NAME>.yaml (only called when {#local_manifest?} is true).
+    def read_local_manifest(name)
+      File.read(manifest_path(name))
+    end
+
+    def manifest_path(name)
+      File.join(Dir.pwd, "#{name}.yaml")
+    end
+
+    # Validate the positional identifiers at the CLI boundary, before any editor,
+    # cluster, or filesystem work -- this is the security gate against path
+    # traversal and argument injection (see {RKSeal::Secret.validate_identifier!}).
+    def validate_identifiers!(namespace, name)
+      Secret.validate_identifier!(field: "namespace", value: namespace)
+      Secret.validate_identifier!(field: "name", value: name)
+    end
+
+    # Translate the dashed CLI scope string into the symbol the command expects.
+    # Thor's enum has already constrained it to a known value. Returns nil when
+    # `--scope` was not given (only `edit` omits the default, so it can preserve
+    # the secret's existing scope).
+    def scope_symbol
+      value = options["scope"]
+      value.nil? ? nil : SCOPE_SYMBOLS.fetch(value)
+    end
+
+    # Parse repeatable `--from-file key=path` tokens into a {key => path} Hash.
+    # Splitting on the first "=" only keeps paths that contain "=" intact.
+    #
+    # @return [Hash{String=>String}, nil] nil when the flag was not given.
+    def parsed_from_file
+      entries = options["from-file"]
+      return nil if entries.nil?
+
+      entries.each_with_object({}) do |entry, acc|
+        key, path = entry.split("=", 2)
+        if key.nil? || key.empty? || path.nil? || path.empty?
+          raise InvalidInputError, "--from-file expects key=path, got #{entry.inspect}"
+        end
+
+        acc[key] = path
+      end
+    end
+
+    # Build the kubeseal adapter from the cert/controller options. Dashed option
+    # names are string keys (Thor does not auto-underscore them). `--refresh-cert`
+    # bypasses the cert cache (`Kubeseal.new(refresh_cert:)`); it defaults to
+    # false for every command that builds a kubeseal adapter.
+    #
+    # The controller name/namespace are Kubernetes identifiers that flow into the
+    # on-disk cert-cache path, so they are validated as DNS-1123 here (same gate
+    # as the positional args) -- this prevents `../`, `/`, a leading `-`, or NUL
+    # from escaping the cache directory before any path is built.
+    def build_kubeseal
+      controller_name = validated_controller("controller-name")
+      controller_namespace = validated_controller("controller-namespace")
+      Kubeseal.new(
+        cert: options["cert"],
+        controller_name: controller_name,
+        controller_namespace: controller_namespace,
+        refresh_cert: options.fetch("refresh-cert", false)
+      )
+    end
+
+    # Validate a controller flag as a DNS-1123 name when present; pass nil through
+    # untouched (the adapter falls back to its own defaults).
+    def validated_controller(flag)
+      value = options[flag]
+      return nil if value.nil?
+
+      Secret.validate_identifier!(field: "--#{flag}", value: value)
+    end
+
+    # Print a one-line outcome. A nil output_path means the edit was a no-op.
+    def report(result)
+      if result.output_path.nil?
+        say("No changes; nothing written.")
+        return
+      end
+
+      say("Wrote #{result.output_path}")
+      say("Deployed #{result.secret_name} to the cluster.") if result.deployed
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end