vagrant-docker-certificates-manager 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 023a4ac2fc48aacbf0de2d60bfa2b91a8890318b623c2169538ea748db884367
+  data.tar.gz: 8b709c9e9c8a637e80df487b3ca0381e9ff1cd0c2334941024819a842050e4b6
+SHA512:
+  metadata.gz: 2cdba816ec1797ad404199e153bdb3e25b9b105bc62ea872d1068efbdaf0649e9e80ea8b1044c46f966b19e19cda29c85fb09c80af5632cf1acbe794e3152fc0
+  data.tar.gz: 8697e75304b157574141dc5b7ebeef2d81ffcc4c6bb27d23277f45f25418a40bb8c1e3de045f8b7bb418adfff601d3eb7058b2af15df97d4ecf16e92f324274e

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/julienpoirou/vagrant-docker-certificates-manager/compare/v0.1.0...v0.2.0) (2025-08-20)
+
+
+### Fonctionnalités ✨
+
+* **init:** V0.1.0 ([e3a22bf](https://github.com/julienpoirou/vagrant-docker-certificates-manager/commit/e3a22bf18484e23106d2cca9d0ef9c67618956f8))

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+===========
+
+Copyright (c) 2025 Julien Poirou <julienpoirou@protonmail.com>
+
+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,197 @@
+# vagrant-docker-certificates-manager
+
+[![CI](https://github.com/julienpoirou/vagrant-docker-certificates-manager/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/julienpoirou/vagrant-docker-certificates-manager/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/julienpoirou/vagrant-docker-certificates-manager/actions/workflows/codeql.yml/badge.svg)](https://github.com/julienpoirou/vagrant-docker-certificates-manager/actions/workflows/codeql.yml)
+[![Release](https://img.shields.io/github/v/release/julienpoirou/vagrant-docker-certificates-manager?include_prereleases&sort=semver)](https://github.com/julienpoirou/vagrant-docker-certificates-manager/releases)
+[![RubyGems](https://img.shields.io/gem/v/vagrant-docker-certificates-manager.svg)](https://rubygems.org/gems/vagrant-docker-certificates-manager)
+[![License](https://img.shields.io/github/license/julienpoirou/vagrant-docker-certificates-manager.svg)](LICENSE.md)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196.svg)](https://www.conventionalcommits.org)
+[![Renovate](https://img.shields.io/badge/Renovate-enabled-brightgreen.svg)](https://renovatebot.com)
+[![Total downloads](https://img.shields.io/gem/dt/vagrant-docker-certificates-manager?logo=rubygems&label=downloads)](https://rubygems.org/gems/vagrant-docker-certificates-manager)
+
+Vagrant plugin to **install/uninstall a local Root CA certificate** into the host system trust stores and (optionally) browser NSS stores. Works on **macOS, Linux and Windows**.
+
+- Can install the certificate on `vagrant up` (opt‑in)
+- CLI: `vagrant certs add | remove | list | version | help`
+- Optional support for Firefox and Chromium-based browsers (NSS)
+- Multilingual output (**en**, **fr**) and `--no-emoji` option
+
+> Requirements: **Vagrant ≥ 2.2**, **Ruby ≥ 3.1**.  
+> For Linux: `update-ca-certificates` (Debian/Ubuntu) and optional `libnss3-tools` for browser stores.  
+> ⚠️ **Only install certificates you trust**.
+
+---
+
+## Table of contents
+
+- [Why this plugin?](#why-this-plugin)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Vagrantfile configuration](#vagrantfile-configuration)
+- [CLI usage](#cli-usage)
+- [How it works](#how-it-works)
+- [OS-specific notes](#os-specific-notes)
+- [Environment variables](#environment-variables)
+- [Troubleshooting](#troubleshooting)
+- [Contributing & Development](#contributing--development)
+- [License](#license)
+
+> 🇫🇷 **Français :** voir [README.fr.md](README.fr.md)
+
+---
+
+## Why this plugin?
+
+Local development with HTTPS often relies on a **local CA** (e.g. `rootca.cert.pem`) to sign project certificates (`*.local`). Manually adding that CA to each teammate’s **system trust store** and **browser** is tedious and error‑prone. This plugin makes it **repeatable**, **scriptable** and **cross‑platform**.
+
+---
+
+## Installation
+
+From RubyGems (once published):
+
+```bash
+vagrant plugin install vagrant-docker-certificates-manager
+```
+
+From source:
+
+```bash
+git clone https://github.com/julienpoirou/vagrant-docker-certificates-manager
+cd vagrant-docker-certificates-manager
+bundle install
+rake
+vagrant plugin install .
+```
+
+---
+
+## Quick start
+
+### Minimal Vagrantfile
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "hashicorp/ubuntu-22.04"
+
+  # Required
+  config.docker_certificates.cert_path = "./certs/rootca.cert.pem" # your Root CA
+  config.docker_certificates.cert_name = "noesi.local"
+
+  # Optional
+  config.docker_certificates.install_on_up       = true  # auto-install on `vagrant up`
+  # config.docker_certificates.manage_firefox      = true
+  # config.docker_certificates.manage_nss_browsers = true
+  # config.docker_certificates.locale              = "fr" # or "en"
+end
+```
+
+Bring the VM up:
+
+```bash
+vagrant up
+```
+
+This will attempt to install the CA into the host trust store (and optional browsers) using OS-specific commands.
+
+---
+
+## Vagrantfile configuration
+
+| Key                       | Type    | Default  | Description |
+|---------------------------|---------|----------|-------------|
+| `cert_path`               | String  | `nil`    | **Required.** Path to your Root CA PEM file on the **host**. |
+| `cert_name`               | String  | `local.dev` | Display/friendly name for OS/browser stores. |
+| `install_on_up`           | Bool    | `false`  | Install automatically during `vagrant up`. |
+| `manage_firefox`          | Bool    | `false`  | Attempt to add CA to Firefox profiles (if found). |
+| `manage_nss_browsers`     | Bool    | `true`   | Attempt to add CA to user NSS DB (Chromium/Brave/etc.). |
+| `locale`                  | String  | `"en"`   | Language for messages (`"en"` or `"fr"`). |
+| `verbose`                 | Bool    | `false`  | Print extra diagnostics (when supported). |
+
+**Validation**  
+- `cert_path` must exist and be a file.  
+- On Linux, you may need `sudo` and `libnss3-tools` for browser stores.
+
+---
+
+## CLI usage
+
+```
+vagrant certs <command> [--lang en|fr] [--no-emoji]
+
+Commands:
+  add <PATH>       Install the CA from PATH into system/browser stores
+  remove <PATH>    Remove the CA that was installed from PATH
+  list             Show tracked certificates installed via this plugin
+  version          Print plugin version
+  help [TOPIC]     Show help (topics: add, remove, list, version, help)
+```
+
+Examples:
+
+```bash
+vagrant certs add ./certs/rootca.cert.pem
+vagrant certs remove ./certs/rootca.cert.pem --lang fr
+vagrant certs list --no-emoji
+vagrant certs version
+vagrant certs help add
+```
+
+---
+
+## How it works
+
+- **macOS**: uses `security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain` to add a CA; removal via `security delete-certificate -Z <sha1>`.
+- **Linux (Debian/Ubuntu)**: copies the CA into `/usr/local/share/ca-certificates/<name>.crt` and runs `update-ca-certificates`. For browser stores, uses `certutil` (NSS) if present and profiles are found.  
+- **Windows**: uses `certutil -addstore -f ROOT <path>` to add the CA to the “Trusted Root Certification Authorities”; removal via `certutil -delstore ROOT <thumbprint>`.
+
+The plugin can also auto‑install on `vagrant up` when `install_on_up` is `true`.
+
+---
+
+## OS-specific notes
+
+- **Privileges**: writing to system trust stores often needs **Admin/root**. You may be prompted for your password or need to run an elevated shell.
+- **Firefox**: when enabled, the plugin scans for profiles (native, Flatpak, Snap on Linux). If `certutil` is not installed, Firefox integration is skipped.
+- **NSS browsers**: for Chromium/Brave/Opera/etc., we try `~/.pki/nssdb` or browser-specific profile DBs. Behavior varies by distro and packaging.
+- **PEM format**: the Root CA should be in PEM. If needed, convert with `openssl x509 -in rootca.crt -out rootca.pem -outform pem`.
+
+---
+
+## Environment variables
+
+| Variable        | Purpose |
+|-----------------|---------|
+| `VDCM_LANG`     | Force language (`en`/`fr`) regardless of config. |
+| `VDCM_NO_EMOJI` | When `1`, disables emoji in output. |
+| `VDCM_DEBUG`    | When `1`, prints extra debug logs from the plugin. |
+
+---
+
+## Troubleshooting
+
+- **Permission denied**: run an elevated shell (Admin on Windows, `sudo` on Linux/macOS) or allow the password prompt.
+- **Linux: `certutil` missing**: install NSS tools, e.g. `sudo apt-get update && sudo apt-get install -y libnss3-tools`.
+- **Firefox not updated**: ensure Firefox is closed; confirm the profile directories exist; Flatpak/Snap paths differ.
+- **Wrong certificate**: verify the file path and format (`*.pem`). Check with `openssl x509 -in rootca.pem -text -noout`.
+
+---
+
+## Contributing & Development
+
+```bash
+git clone https://github.com/julienpoirou/vagrant-docker-certificates-manager
+cd vagrant-docker-certificates-manager
+bundle install
+rake          # runs RSpec
+```
+
+- Conventional Commits are welcome.
+- CI runs tests and linting.
+- Issues and PRs are appreciated!
+
+---
+
+## License
+
+MIT © 2025 Julien Poirou

data/lib/vagrant-docker-certificates-manager/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/vagrant-docker-certificates-manager/actions/install.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../util/os"
+require_relative "../util/ui"
+require_relative "../util/cert"
+require_relative "../util/registry"
+require_relative "../helpers"
+
+module VagrantDockerCertificatesManager
+  module Actions
+    class Install
+      def initialize(app, env); @app = app; @env = env; end
+
+      def call(env)
+        cfg = env[:machine].config.docker_certificates
+        UiHelpers.set_locale!(cfg.locale || ENV["LANG"] || "en")
+        if cfg.install_on_up
+          Ui.say(env, :info, "install.start", name: cfg.cert_name, path: cfg.cert_path)
+          result = self.class.perform_install(cfg, env)
+          Ui.say(env, result[:status] == "success" ? :info : :error,
+                 result[:status] == "success" ? "install.success" : "install.fail",
+                 name: cfg.cert_name)
+        end
+        @app.call(env)
+      end
+
+      def self.perform_install(cfg, env)
+        unless File.file?(cfg.cert_path)
+          return { code: 1, status: "error",
+error: UiHelpers.t("errors.invalid_path", path: cfg.cert_path) }
+        end
+
+        name = cfg.cert_name.to_s.strip.empty? ? Cert.default_name_from(cfg.cert_path) : cfg.cert_name
+        fp   = Cert.sha1(cfg.cert_path)
+        if Registry.all.key?(fp)
+          return { code: 1, status: "error",
+error: UiHelpers.t("errors.already_present", name: name) }
+        end
+
+        os = OS.detect
+        ok = case os
+             when :mac     then OS.mac_add_trusted_cert(cfg.cert_path, name)
+             when :linux   then OS.linux_install_cert(cfg.cert_path, name, nss: cfg.manage_nss_browsers,
+firefox: cfg.manage_firefox)
+             when :windows then OS.win_install_cert(cfg.cert_path, name)
+             else return { code: 2, status: "error", error: UiHelpers.t("errors.os_unsupported") }
+             end
+        return({ code: 3, status: "error", error: UiHelpers.t("errors.install_failed") }) unless ok
+
+        Registry.track(fp, {
+          "path"      => File.expand_path(cfg.cert_path),
+          "name"      => name,
+          "nickname"  => Cert.nickname_for(name),
+          "os"        => os.to_s
+        })
+        { code: 0, status: "success", data: { os: os, cert: name } }
+      end
+    end
+  end
+end

data/lib/vagrant-docker-certificates-manager/actions/uninstall.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../util/os"
+require_relative "../util/ui"
+require_relative "../util/cert"
+require_relative "../util/registry"
+require_relative "../helpers"
+
+module VagrantDockerCertificatesManager
+  module Actions
+    class Uninstall
+      def initialize(app, env); @app = app; @env = env; end
+
+      def call(env)
+        cfg = env[:machine].config.docker_certs
+        UiHelpers.set_locale!(cfg.locale || "en")
+        if cfg.remove_on_destroy
+          Ui.say(env, :info, "uninstall.start", name: cfg.cert_name)
+          result = self.class.perform_uninstall(cfg, env)
+          Ui.say(env, result[:status] == "success" ? :info : :warn,
+                 result[:status] == "success" ? "uninstall.success" : "uninstall.fail",
+                 name: cfg.cert_name)
+        end
+        @app.call(env)
+      end
+
+      def self.perform_uninstall(cfg, _env)
+        fp_entry = Registry.find_by_path(cfg.cert_path)
+        unless fp_entry
+          return({ code: 1, status: "error",
+                   error: UiHelpers.t("errors.not_found_for_remove", path: cfg.cert_path) })
+        end
+        fp, rec = fp_entry
+        os = OS.detect
+        ok = case os
+             when :mac     then OS.mac_remove_by_fp(fp)
+             when :linux   then OS.linux_uninstall_cert(rec["name"], nss: cfg.manage_nss_browsers,
+                                                                     firefox: cfg.manage_firefox)
+             when :windows then OS.win_remove_by_fp(fp)
+             else return({ code: 2, status: "error", error: UiHelpers.t("errors.os_unsupported") })
+             end
+        Registry.untrack(fp) if ok
+        ok ? { code: 0, status: "success" } : { code: 4, status: "error", error: UiHelpers.t("errors.remove_failed") }
+      end
+    end
+  end
+end

data/lib/vagrant-docker-certificates-manager/command.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "util/ui"
+require_relative "util/cert"
+require_relative "util/registry"
+require_relative "util/os"
+require_relative "version"
+require_relative "helpers"
+
+module VagrantDockerCertificatesManager
+  BASE_CMD = if defined?(Vagrant) && Vagrant.respond_to?(:plugin)
+               Vagrant.plugin("2", :command)
+             else
+               Class.new do
+                 def initialize(argv = [], env = {})
+                   @argv = argv || []
+                   @env  = env  || {}
+                 end
+
+                 def parse_options(parser)
+                   parser.order!(@argv)
+                   @argv
+                 rescue OptionParser::InvalidOption
+                   nil
+                 end
+               end
+             end
+
+  class Command < BASE_CMD
+    def initialize(*args)
+      argv, env =
+        if args.size == 2 && args.first.is_a?(Array)
+          [args.first, args.last]
+        elsif args.size == 2 && args.last.is_a?(Array)
+          [args.last, args.first]
+        else
+          [args[0].is_a?(Array) ? args[0] : [], args[1] || {}]
+        end
+
+      super(argv, env) if defined?(super)
+      @argv = argv
+      @env  = env
+    end
+
+    def execute
+      UiHelpers.setup_i18n!
+
+      opts = { lang: nil, no_emoji: false }
+
+      parser = OptionParser.new do |o|
+        o.banner = UiHelpers.t("cli.usage", default: "Usage: vagrant certs <add|remove|list|version|help> [options]")
+        o.on("--lang LANG", UiHelpers.t("cli.opt_lang", default: "Force language (en|fr)")) { |v| opts[:lang] = v }
+        o.on("--no-emoji",  UiHelpers.t("cli.opt_no_emoji", default: "Disable emoji in CLI output")) do
+          opts[:no_emoji] = true
+        end
+        o.on("-h", "--help", UiHelpers.t("cli.opt_help", default: "Show help and exit")) do
+          UiHelpers.print_general_help(no_emoji: opts[:no_emoji], ui: @env.ui)
+          return 0
+        end
+      end
+
+      argv = parse_options(parser)
+      return 0 unless argv
+
+      UiHelpers.set_locale!(opts[:lang] || "en")
+      ENV["VDCM_NO_EMOJI"] = "1" if opts[:no_emoji]
+
+      env = { ui: @env.ui, no_emoji: opts[:no_emoji] }
+
+      sub = argv.shift
+      case sub
+      when "add", "install"
+        path = argv.shift
+        unless path && File.file?(path)
+          Ui.say(env, :error, "errors.invalid_path", path: (path || "").to_s)
+          return 1
+        end
+
+        name = Cert.default_name_from(path)
+        fp   = Cert.sha1(path)
+        nick = Cert.nickname_for(name)
+
+        if Registry.all.key?(fp)
+          Ui.say(env, :error, "errors.already_present", name: name)
+          return 1
+        end
+
+        os = OS.detect
+        ok = case os
+             when :mac
+               OS.mac_has_cert_fingerprint?(fp) ? false : OS.mac_add_trusted_cert(path, name)
+             when :linux
+               OS.linux_has_cert_file?(name) ? false : OS.linux_install_cert(path, name, nss: true, firefox: false)
+             when :windows
+               OS.win_has_cert_fingerprint?(fp) ? false : OS.win_install_cert(path, name)
+             else
+               Ui.say(env, :error, "errors.os_unsupported")
+               return 2
+             end
+
+        unless ok
+          Ui.say(env, :error, "errors.install_failed")
+          return 3
+        end
+
+        Registry.track(fp, {
+          "path"      => File.expand_path(path),
+          "name"      => name,
+          "nickname"  => nick,
+          "os"        => os.to_s
+        })
+        Ui.say(env, :info, "add.success", name: name)
+        0
+
+      when "remove", "uninstall"
+        path = argv.shift
+        unless path && !path.strip.empty?
+          Ui.say(env, :error, "errors.missing_path_remove")
+          return 1
+        end
+
+        fp = if File.file?(path)
+               Cert.sha1(path)
+             else
+               (Registry.find_by_path(path) || [nil]).first
+             end
+
+        unless fp
+          Ui.say(env, :error, "errors.not_found_for_remove", path: path)
+          return 1
+        end
+
+        name_for_remove = (Registry.all[fp] || {})["name"] || Cert.default_name_from(path)
+
+        os = OS.detect
+        ok = case os
+             when :mac     then OS.mac_remove_by_fp(fp)
+             when :linux   then OS.linux_uninstall_cert(name_for_remove)
+             when :windows then OS.win_remove_by_fp(fp)
+             else
+               Ui.say(env, :error, "errors.os_unsupported")
+               return 2
+             end
+
+        if ok
+          Registry.untrack(fp)
+          Ui.say(env, :info, "remove.success")
+          0
+        else
+          Ui.say(env, :warn, "errors.remove_failed")
+          4
+        end
+
+      when "list", "status"
+        entries = Registry.all
+        if entries.empty?
+          Ui.say(env, :info, "list.empty")
+          return 0
+        end
+        Ui.say(env, :info, "list.header")
+        entries.each do |fp, v|
+          @env.ui.info("  • #{v['name']}  (#{fp})  [#{v['os']}]  #{v['path']}")
+        end
+        0
+
+      when "version"
+        emoji = UiHelpers.e(:version, no_emoji: opts[:no_emoji])
+        line  = UiHelpers.t("messages.version_line", default: "v%{v}.", v: VagrantDockerCertificatesManager::VERSION)
+        @env.ui.info("#{emoji} #{line}".strip)
+        0
+
+      when "help", "helps", nil, ""
+        topic = argv.shift
+        if topic && !topic.strip.empty?
+          UiHelpers.print_topic_help(topic, no_emoji: opts[:no_emoji], ui: @env.ui)
+        else
+          UiHelpers.print_general_help(no_emoji: opts[:no_emoji], ui: @env.ui)
+        end
+        0
+
+      else
+        Ui.say(env, :error, "errors.unknown_command", cmd: sub)
+        UiHelpers.print_general_help(no_emoji: opts[:no_emoji], ui: @env.ui)
+        1
+      end
+    end
+  end
+end

data/lib/vagrant-docker-certificates-manager/config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module VagrantDockerCertificatesManager
+  class Config < Vagrant.plugin("2", :config)
+    attr_accessor :cert_path, :cert_name, :install_on_up, :remove_on_destroy,
+                  :manage_firefox, :manage_nss_browsers, :locale, :verbose,
+                  :container_name
+
+    def initialize
+      @cert_path            = "certs/rootca.cert.pem"
+      @cert_name            = "local.dev"
+      @install_on_up        = false
+      @remove_on_destroy    = false
+      @manage_firefox       = false
+      @manage_nss_browsers  = true
+      @locale               = "en"
+      @verbose              = false
+      @container_name       = nil
+    end
+
+    def finalize!
+      @cert_path = @container_name unless @container_name.to_s.strip.empty?
+      @install_on_up       = !!@install_on_up
+      @remove_on_destroy   = !!@remove_on_destroy
+      @manage_firefox      = !!@manage_firefox
+      @manage_nss_browsers = !!@manage_nss_browsers
+      @verbose             = !!@verbose
+      @locale              = (@locale || "en").to_s
+    end
+
+    def validate(_machine)
+      errors = []
+      errors << "cert_path must be provided" if @cert_path.to_s.strip.empty?
+      errors << "cert_name must be provided" if @cert_name.to_s.strip.empty?
+      { "vagrant-docker-certificates-manager" => errors }
+    end
+  end
+end