kairos-chain 3.39.0 → 3.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0da61a60c3ecd5e32e85052668638f65522376949dc5577a54ab5db754e7118a
-  data.tar.gz: fe8f12657d7032c9047368372dd6e49bc733e83804a55c83717608980d0017bc
+  metadata.gz: 2285b28e2f2954ca10f6da869b7446b4d18fdc0f9174451f20ec8f523142b322
+  data.tar.gz: 9a14c47fd141de6ff7eaec10d6e56c44f01e96b1cb0b9ab962eedb4baccc8e4b
 SHA512:
-  metadata.gz: 6e466478fd4e87509d7b4efa1218813fba0f395ea2296852a69b4f2190070ddddf59b2a8961f4b1a34d71ad4d1666716df105ad609f21e6ac9f91e228a58dbf8
-  data.tar.gz: 4cf41c84ff411cb3e18de05683343eb3f84a3281c7f93461ec90c6ea4806919ebf58ae70694e0e629248189411b6b815d764cb3e10f6956d502f5222fc60cc46
+  metadata.gz: 89a5a8a47b38f8f703283c58d9e402efeab1a2124fa1ad2195c0820edd985301ce68b22dd40012614499d09f9b34410905e473ca33ccad97e8d32d804ba46eb1
+  data.tar.gz: df15f0d5f6cdb22039840cf780b235cba8194e77da2738478b37dbeb446c25814609887083566388bae2abeb2f067e0aa2ecb24d16b4ca626b75644818d794eb

data/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.40.0] - 2026-07-06
+
+### Added — Optional built-in TLS/HTTPS for the HTTP transport
+
+Opt-in TLS termination for the Puma-based MCP HTTP server, so a self-hosted
+instance can be reached securely over the network without a reverse proxy.
+Encryption is delegated to Puma/OpenSSL (Prop 2: transport is execution
+substrate); KairosChain only selects the bind scheme and can generate a
+self-signed certificate for single-operator use. Default remains plain HTTP
+(backward compatible).
+
+- **`TlsConfig`** — `tcp://` vs `ssl://` bind selection, fail-closed validation
+  (exists + readable + valid PEM + cert/key pair match), IPv6 host bracketing,
+  certificate-expiry reporting.
+- **`TlsCertGenerator`** — self-signed leaf certificate via the OpenSSL stdlib:
+  `CA:FALSE`, `keyUsage` + `extendedKeyUsage=serverAuth`, SAN built from a host
+  list (loopback + system hostname + config host + `--cert-host`), positive
+  serial, atomic `0600` private-key write.
+- **`HttpServer`** — `--tls` bind, startup certificate-expiry warning, and
+  fail-closed refusal to start an unauthenticated endpoint on a network-reachable
+  bind (override with `KAIROS_ALLOW_OPEN_ENDPOINT=1`).
+- **CLI** — `--tls`, `--gen-cert`, `--cert-host`; `--init-admin` sample URL
+  scheme resolved from config + flag.
+- **Config** — `http.tls` block (default disabled).
+- **Docs** — `kairoschain_setup` knowledge (en/jp) documents built-in TLS
+  (Option A) alongside the reverse-proxy path (Option B).
+
+Reviewed via a 2-round multi-LLM review (R1 raised 3 P1 + P2s; R2 verified all
+resolved). 36/36 HTTP tests pass; verified end-to-end with a real
+certificate-verified HTTPS handshake and the fail-closed guard matrix.
+
 ## [3.39.0] - 2026-07-05
 
 ### Added — L1 `multi_llm_review_workflow` v3.5 → v3.6: Step 0.25 Unknowns Pass

data/bin/kairos-chain

@@ -636,10 +636,22 @@ OptionParser.new do |opts|
     options[:port] = port
   end
 
-  opts.on('--host HOST', 'HTTP bind host (default: 0.0.0.0)') do |host|
+  opts.on('--host HOST', 'HTTP bind host (default: config http.host, else 127.0.0.1)') do |host|
     options[:host] = host
   end
 
+  opts.on('--tls', 'Enable TLS (HTTPS) for --http mode (overrides config)') do
+    options[:tls] = true
+  end
+
+  opts.on('--gen-cert', 'Generate a self-signed TLS cert/key for --tls and exit') do
+    options[:gen_cert] = true
+  end
+
+  opts.on('--cert-host HOST', 'Add a hostname/IP to the generated cert SAN (repeatable)') do |h|
+    (options[:cert_hosts] ||= []) << h
+  end
+
   opts.on('--init-admin', 'Generate initial admin token and exit') do
     options[:init_admin] = true
   end
@@ -715,6 +727,72 @@ if options[:version]
   exit
 end
 
+# Handle --gen-cert (generate self-signed TLS certificate and exit)
+if options[:gen_cert]
+  require 'kairos_mcp/tls_config'
+  require 'kairos_mcp/tls_cert_generator'
+  require 'kairos_mcp/skills_config'
+
+  http_config = KairosMcp::SkillsConfig.load['http'] || {}
+  tls = KairosMcp::TlsConfig.new(http_config, data_dir: KairosMcp.data_dir, force_enabled: true)
+
+  cert_exists = File.exist?(tls.cert_path) || File.exist?(tls.key_path)
+  if cert_exists
+    $stderr.puts "[gen-cert] A cert/key already exists:"
+    $stderr.puts "  cert: #{tls.cert_path}" if File.exist?(tls.cert_path)
+    $stderr.puts "  key:  #{tls.key_path}" if File.exist?(tls.key_path)
+    if KairosMcp::TlsCertGenerator.overwrite_refused_noninteractive?(exists: cert_exists, tty: $stdin.tty?)
+      $stderr.puts "[gen-cert] Non-interactive mode: refusing to overwrite. Delete the files to regenerate."
+      exit 1
+    else
+      $stderr.puts ""
+      $stderr.puts "Overwrite? (y/N)"
+      answer = $stdin.gets&.strip
+      exit unless answer&.downcase == 'y'
+    end
+  end
+
+  # Build the SAN host list: loopback defaults + system hostname + config host
+  # + any --cert-host entries. Without this the cert only covers localhost and
+  # remote clients connecting by hostname/IP fail certificate verification.
+  require 'socket'
+  san_hosts = KairosMcp::TlsCertGenerator::DEFAULT_HOSTS.dup
+  begin
+    san_hosts << Socket.gethostname
+  rescue StandardError
+    # hostname is best-effort; loopback defaults still apply
+  end
+  cfg_host = http_config['host']
+  san_hosts << cfg_host unless cfg_host.nil? || ['0.0.0.0', '::', ''].include?(cfg_host)
+  san_hosts.concat(Array(options[:cert_hosts]))
+
+  result = KairosMcp::TlsCertGenerator.generate(
+    cert_path: tls.cert_path, key_path: tls.key_path, hosts: san_hosts
+  )
+
+  $stderr.puts ""
+  $stderr.puts "=" * 60
+  $stderr.puts "  Self-signed TLS certificate generated"
+  $stderr.puts "=" * 60
+  $stderr.puts "  cert:     #{result[:cert_path]}"
+  $stderr.puts "  key:      #{result[:key_path]} (chmod 0600)"
+  $stderr.puts "  expires:  #{result[:not_after]}"
+  $stderr.puts "  SAN:      #{result[:san]}"
+  $stderr.puts ""
+  $stderr.puts "  If you access this server by a hostname/IP not listed in SAN,"
+  $stderr.puts "  regenerate with:  kairos-chain --gen-cert --cert-host <name>"
+  $stderr.puts ""
+  $stderr.puts "  Enable TLS by either:"
+  $stderr.puts "    - starting with:  kairos-chain --http --tls"
+  $stderr.puts "    - or setting http.tls.enabled: true in skills/config.yml"
+  $stderr.puts ""
+  $stderr.puts "  NOTE: self-signed certs are for single-operator use. Clients"
+  $stderr.puts "  must trust this cert (or disable verification). For a public"
+  $stderr.puts "  service use a CA-issued cert behind a reverse proxy."
+  $stderr.puts "=" * 60
+  exit
+end
+
 # Handle --init-admin
 if options[:init_admin]
   require 'kairos_mcp/auth/token_store'
@@ -734,6 +812,13 @@ if options[:init_admin]
     store_path = File.join(KairosMcp.data_dir, store_path)
   end
 
+  # Resolve the actual scheme from TlsConfig (config OR --tls), not from the
+  # --tls flag alone — otherwise config-enabled TLS prints an http:// URL.
+  require 'kairos_mcp/tls_config'
+  admin_scheme = KairosMcp::TlsConfig.new(
+    http_config, data_dir: KairosMcp.data_dir, force_enabled: options[:tls]
+  ).scheme
+
   store = KairosMcp::Auth::TokenStore.create(
     backend: http_config['token_backend'],
     store_path: store_path
@@ -790,9 +875,9 @@ if options[:init_admin]
   $stderr.puts "  {"
   $stderr.puts "    \"mcpServers\": {"
   $stderr.puts "      \"kairos\": {"
-  $stderr.puts "        \"url\": \"http://localhost:#{options[:port] || 8080}/mcp\","
+  $stderr.puts "        \"url\": \"#{admin_scheme}://localhost:#{options[:port] || 8080}/mcp\","
   $stderr.puts "        \"headers\": {"
-  $stderr.puts "          \"Authorization\": \"Bearer #{result['raw_token']}\""
+  $stderr.puts "          \"Authorization\": \"Bearer #{result[:raw_token] || result['raw_token']}\""
   $stderr.puts "        }"
   $stderr.puts "      }"
   $stderr.puts "    }"
@@ -817,7 +902,8 @@ if options[:http]
   server = KairosMcp::HttpServer.new(
     port: options[:port],
     host: options[:host],
-    token_store_path: options[:token_store]
+    token_store_path: options[:token_store],
+    tls: options[:tls]
   )
   server.run
 else

data/lib/kairos_mcp/http_server.rb

@@ -9,6 +9,7 @@ require_relative '../kairos_mcp'
 require_relative 'auth/token_store'
 require_relative 'auth/authenticator'
 require_relative 'skills_config'
+require_relative 'tls_config'
 require_relative 'admin/router'
 require_relative 'meeting_router'
 
@@ -39,14 +40,19 @@ module KairosMcp
       'Cache-Control' => 'no-cache'
     }.freeze
 
-    attr_reader :port, :host, :token_store, :authenticator, :admin_router, :meeting_router, :place_router
+    attr_reader :port, :host, :token_store, :authenticator, :admin_router,
+                :meeting_router, :place_router, :tls
 
-    def initialize(port: nil, host: nil, token_store_path: nil)
+    def initialize(port: nil, host: nil, token_store_path: nil, tls: nil)
       http_config = SkillsConfig.load['http'] || {}
 
       @port = port || http_config['port'] || DEFAULT_PORT
       @host = host || http_config['host'] || DEFAULT_HOST
 
+      # TLS is opt-in and delegated to Puma/OpenSSL (Prop 2: execution
+      # substrate). `tls: true` from the CLI (--tls) overrides the config.
+      @tls = TlsConfig.new(http_config, data_dir: KairosMcp.data_dir, force_enabled: tls)
+
       # SkillSets must load BEFORE TokenStore.create so that plugins
       # (e.g. Multiuser) can register alternative backends first.
       eager_load_skillsets
@@ -79,6 +85,7 @@ module KairosMcp
     def run
       KairosMcp.http_server = self
       check_dependencies!
+      check_tls!
       check_tokens!
       check_version_mismatch
       auto_start_meeting_place
@@ -87,7 +94,9 @@ module KairosMcp
       server = self
 
       log "Starting KairosChain MCP Server v#{VERSION} (Streamable HTTP)"
-      log "Listening on #{@host}:#{@port}"
+      log "Listening on #{@tls.scheme}://#{@host}:#{@port}"
+      log "TLS: #{@tls.enabled? ? "enabled (cert: #{@tls.cert_path})" : 'disabled (plain HTTP)'}"
+      log_tls_expiry
       log "MCP endpoint: POST /mcp"
       log "Health check: GET /health"
       log "Admin UI:     GET /admin"
@@ -99,7 +108,7 @@ module KairosMcp
       require 'puma/launcher'
 
       puma_config = Puma::Configuration.new do |config|
-        config.bind "tcp://#{server.host}:#{server.port}"
+        config.bind server.bind_uri
         config.app app
         config.workers 0
         config.threads 1, 5
@@ -176,6 +185,7 @@ module KairosMcp
         server: 'kairos-chain',
         version: KairosMcp::VERSION,
         transport: 'streamable-http',
+        tls: @tls.enabled?,
         tokens_configured: !@token_store.empty?,
         place_started: !@place_router.nil?
       }
@@ -296,8 +306,63 @@ module KairosMcp
       [status, JSON_HEADERS, [body_hash.to_json]]
     end
 
+    # Puma bind URI for the configured host/port. Scheme (tcp:// vs ssl://)
+    # is decided by TlsConfig. Public for testability.
+    def bind_uri
+      @tls.bind_uri(@host, @port)
+    end
+
     private
 
+    # Fail-closed TLS check: if TLS is enabled but cert/key are missing,
+    # abort with actionable guidance rather than starting plain HTTP.
+    def check_tls!
+      @tls.validate!
+    rescue TlsConfigError => e
+      $stderr.puts "[ERROR] #{e.message}"
+      exit 1
+    end
+
+    # Surface certificate expiry so a self-signed cert does not silently stop
+    # working after its validity window (no auto-renewal for --gen-cert).
+    EXPIRY_WARN_DAYS = 30
+
+    def log_tls_expiry
+      return unless @tls.enabled?
+
+      days = @tls.days_until_expiry
+      return if days.nil?
+
+      not_after = @tls.certificate_not_after
+      if days.negative?
+        $stderr.puts "[WARN] TLS certificate EXPIRED #{-days} day(s) ago (#{not_after}). " \
+                     "Regenerate with 'kairos-chain --gen-cert' (delete the old cert first)."
+      else
+        log "TLS cert expires: #{not_after} (#{days} days)"
+        if days <= EXPIRY_WARN_DAYS
+          $stderr.puts "[WARN] TLS certificate expires in #{days} day(s). " \
+                       "Regenerate with 'kairos-chain --gen-cert' (delete the old cert first)."
+        end
+      end
+    end
+
+    LOOPBACK_HOSTS = ['127.0.0.1', '::1', 'localhost'].freeze
+
+    # Environment opt-out for the fail-closed open-endpoint guard.
+    ALLOW_OPEN_ENDPOINT_ENV = 'KAIROS_ALLOW_OPEN_ENDPOINT'
+
+    def loopback_only?
+      LOOPBACK_HOSTS.include?(@host)
+    end
+
+    # Pure predicate (class method for testability): an empty token store means
+    # unauthenticated owner access. That is only acceptable on a loopback bind
+    # without TLS (local dev). Network-reachable (non-loopback) or TLS-enabled
+    # (remote intent) + empty store = an open owner endpoint.
+    def self.exposed_without_auth?(token_store_empty:, loopback:, tls_enabled:)
+      token_store_empty && (!loopback || tls_enabled)
+    end
+
     # Register place extensions from enabled SkillSets that declare place_extensions.
     # Uses KairosMcp.http_server pattern for late registration access.
     def register_place_extensions(router)
@@ -367,13 +432,49 @@ module KairosMcp
     end
 
     def check_tokens!
-      if @token_store.empty?
+      return unless @token_store.empty?
+
+      # An empty token store means the MCP endpoint accepts unauthenticated
+      # owner-level requests. On loopback without TLS that is convenient
+      # local-dev. Exposed over the network (non-loopback, or TLS = remote
+      # intent) it is an OPEN OWNER ENDPOINT — encrypting an open door.
+      exposed = self.class.exposed_without_auth?(
+        token_store_empty: true, loopback: loopback_only?, tls_enabled: @tls.enabled?
+      )
+
+      unless exposed
         $stderr.puts <<~MSG
           [INFO] Local dev mode: no tokens configured.
           MCP endpoint accepts unauthenticated requests as local owner.
           For production, generate a token with: kairos-chain --init-admin
 
         MSG
+        return
+      end
+
+      # Fail-closed: refuse to start an open owner endpoint on a reachable
+      # bind. The operator can opt out explicitly for intentional cases.
+      if ENV[ALLOW_OPEN_ENDPOINT_ENV] == '1'
+        $stderr.puts <<~MSG
+          [SECURITY] No tokens configured and the endpoint is network-reachable
+          (host=#{@host}#{@tls.enabled? ? ', TLS enabled' : ''}). Starting anyway
+          because #{ALLOW_OPEN_ENDPOINT_ENV}=1. Unauthenticated requests are
+          accepted as owner — anyone who can reach this port has full owner access.
+
+        MSG
+      else
+        $stderr.puts <<~MSG
+          [ERROR] Refusing to start: no tokens configured but the endpoint is
+          network-reachable (host=#{@host}#{@tls.enabled? ? ', TLS enabled' : ''}).
+          Unauthenticated requests would be accepted as owner — TLS encrypts the
+          traffic but does NOT authenticate it, so this is an open owner endpoint.
+
+          Generate an admin token first:  kairos-chain --init-admin
+          Or bind to loopback (host 127.0.0.1) for local-only use.
+          To start intentionally without auth, set #{ALLOW_OPEN_ENDPOINT_ENV}=1.
+
+        MSG
+        exit 1
       end
     end
 

data/lib/kairos_mcp/tls_cert_generator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+require 'fileutils'
+require 'ipaddr'
+
+module KairosMcp
+  # TlsCertGenerator: produce a self-signed certificate + key for the
+  # single-operator remote-access case.
+  #
+  # Design intent (Prop 2): this uses Ruby's OpenSSL stdlib to *generate* key
+  # material — it does not implement any cryptography of its own. It exists so
+  # that "kairos-chain --gen-cert" gives a one-shot path to HTTPS for a single
+  # operator. For a public, multi-user service, use a CA-issued certificate
+  # (e.g. behind a reverse proxy) instead of a self-signed one.
+  module TlsCertGenerator
+    module_function
+
+    # Hostnames/IPs always covered by the generated certificate's SAN so that
+    # loopback access verifies without --cert-host. Remote names are added by
+    # the caller (system hostname, config host, --cert-host entries).
+    DEFAULT_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+    # @param hosts [Array<String>] hostnames/IPs to place in the SAN. Each entry
+    #   is auto-classified as IP: or DNS:. The common_name is always included.
+    # @return [Hash] { cert_path:, key_path:, not_after:, san: }
+    def generate(cert_path:, key_path:, common_name: 'kairos-chain',
+                 hosts: DEFAULT_HOSTS, days: 825, key_size: 2048)
+      key = OpenSSL::PKey::RSA.new(key_size)
+
+      name = OpenSSL::X509::Name.parse("/CN=#{common_name}")
+      cert = OpenSSL::X509::Certificate.new
+      cert.version = 2
+      # Positive, non-zero serial. RFC 5280 requires a positive integer;
+      # SecureRandom.random_number(1 << 64) can return 0, so add 1.
+      cert.serial = OpenSSL::BN.new(SecureRandom.random_number(1 << 64) + 1)
+      cert.subject = name
+      cert.issuer = name
+      cert.public_key = key.public_key
+
+      now = Time.now
+      cert.not_before = now - 3600            # tolerate minor clock skew
+      cert.not_after  = now + (days * 24 * 3600)
+
+      san = san_value(common_name, hosts)
+
+      ef = OpenSSL::X509::ExtensionFactory.new
+      ef.subject_certificate = cert
+      ef.issuer_certificate = cert
+      # Leaf SERVER certificate — explicitly NOT a CA, scoped to serverAuth so
+      # strict clients (macOS Secure Transport, Chromium) accept it.
+      cert.add_extension(ef.create_extension('basicConstraints', 'CA:FALSE', true))
+      cert.add_extension(ef.create_extension('keyUsage', 'digitalSignature,keyEncipherment', true))
+      cert.add_extension(ef.create_extension('extendedKeyUsage', 'serverAuth', false))
+      cert.add_extension(ef.create_extension('subjectAltName', san, false))
+      cert.sign(key, OpenSSL::Digest.new('SHA256'))
+
+      write_secure(cert_path, cert.to_pem, 0o644)
+      write_secure(key_path, key.to_pem, 0o600)
+
+      { cert_path: cert_path, key_path: key_path, not_after: cert.not_after, san: san }
+    end
+
+    # Build a subjectAltName value from a host list, auto-classifying each
+    # entry as IP: or DNS:. The common_name is always included as DNS.
+    def san_value(common_name, hosts)
+      entries = []
+      add_san(entries, common_name)
+      Array(hosts).each { |h| add_san(entries, h) }
+      entries.uniq.join(',')
+    end
+
+    def add_san(entries, host)
+      return if host.nil? || host.to_s.strip.empty?
+
+      h = host.to_s.strip
+      # Reject injection: a raw entry must be a single hostname/IP, not a
+      # comma-separated list or a pre-formatted "DNS:/IP:" token — otherwise
+      # --cert-host "a,DNS:evil" would silently mint extra SAN names.
+      if h.include?(',') || h =~ /\A(DNS|IP):/i
+        raise ArgumentError, "invalid SAN host #{h.inspect}: must be a single hostname or IP"
+      end
+
+      begin
+        IPAddr.new(h)
+        entries << "IP:#{h}"
+      rescue IPAddr::InvalidAddressError, ArgumentError
+        entries << "DNS:#{h}"
+      end
+    end
+
+    # Deterministic half of the --gen-cert overwrite guard: in non-interactive
+    # mode, refuse to clobber an existing cert/key (which could break a live
+    # deployment). Interactive mode prompts the operator instead. Extracted so
+    # the refusal branch is unit-testable.
+    def overwrite_refused_noninteractive?(exists:, tty:)
+      exists && !tty
+    end
+
+    def write_secure(path, content, mode)
+      FileUtils.mkdir_p(File.dirname(path))
+      # Open with target mode (new files) AND chmod the descriptor BEFORE
+      # writing, so on OVERWRITE of a pre-existing world-readable file the key
+      # bytes are never written while the old permissive mode is still in
+      # effect. Closes the umask/overwrite window on both create and overwrite.
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, mode) do |f|
+        f.chmod(mode)
+        f.write(content)
+      end
+    end
+  end
+end

data/lib/kairos_mcp/tls_config.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'openssl'
+
+module KairosMcp
+  # TlsConfig: resolves optional TLS settings for the HTTP transport.
+  #
+  # Design intent (Prop 2, partial autopoiesis): transport encryption is an
+  # execution-substrate concern, not a self-referential core capability.
+  # KairosChain does NOT implement crypto here. It delegates to Puma/OpenSSL
+  # and only decides the bind scheme (tcp:// vs ssl://) from config. The only
+  # logic in this class is path resolution and fail-closed validation.
+  #
+  # Config shape (under the 'http' key of skills/config.yml):
+  #   http:
+  #     tls:
+  #       enabled: false
+  #       cert: "storage/tls/cert.pem"
+  #       key:  "storage/tls/key.pem"
+  #
+  class TlsConfig
+    DEFAULT_CERT = 'storage/tls/cert.pem'
+    DEFAULT_KEY  = 'storage/tls/key.pem'
+
+    attr_reader :cert_path, :key_path
+
+    # @param http_config [Hash] the 'http' section of the loaded config
+    # @param data_dir [String] base dir for resolving relative cert/key paths
+    # @param force_enabled [Boolean, nil] CLI override; nil = use config value
+    def initialize(http_config, data_dir:, force_enabled: nil)
+      tls = (http_config || {})['tls'] || {}
+      @data_dir = data_dir
+      @enabled = force_enabled.nil? ? (tls['enabled'] == true) : force_enabled
+      # An empty-string path in config falls back to the default rather than
+      # resolving to nil (which would crash the --gen-cert path).
+      @cert_path = resolve(present_or(tls['cert'], DEFAULT_CERT))
+      @key_path  = resolve(present_or(tls['key'], DEFAULT_KEY))
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    # Fail-closed validation. When TLS is enabled, the cert and key must exist,
+    # be readable, and parse as valid material — otherwise abort rather than
+    # start plain HTTP or crash later inside Puma with an opaque error.
+    def validate!
+      return unless @enabled
+
+      problems = []
+      problems << "certificate is missing (#{@cert_path})" unless @cert_path && File.exist?(@cert_path)
+      problems << "private key is missing (#{@key_path})" unless @key_path && File.exist?(@key_path)
+
+      if problems.empty?
+        problems << "certificate is not readable (#{@cert_path})" unless File.readable?(@cert_path)
+        problems << "private key is not readable (#{@key_path})" unless File.readable?(@key_path)
+      end
+
+      if problems.empty?
+        cert = safe_parse { OpenSSL::X509::Certificate.new(File.read(@cert_path)) }
+        key  = safe_parse { OpenSSL::PKey.read(File.read(@key_path)) }
+        problems << "certificate is not valid PEM (#{@cert_path})" if cert.nil?
+        problems << "private key is not valid (#{@key_path})" if key.nil?
+        # A parseable cert + parseable key that do not form a pair would pass
+        # independent checks but fail opaquely inside Puma's SSL setup.
+        if cert && key && !cert.check_private_key(key)
+          problems << "certificate and private key do not match (#{@cert_path} / #{@key_path})"
+        end
+      end
+
+      return if problems.empty?
+
+      raise TlsConfigError, <<~MSG.strip
+        TLS is enabled but its material is unusable:
+          - #{problems.join("\n  - ")}
+
+        Generate a self-signed certificate for single-operator use:
+          kairos-chain --gen-cert
+
+        Or point http.tls.cert / http.tls.key at a valid certificate.
+      MSG
+    end
+
+    # Build a Puma bind URI. Encryption params are passed to Puma, which
+    # performs the TLS handshake via OpenSSL.
+    def bind_uri(host, port)
+      h = bracket_ipv6(host)
+      return "tcp://#{h}:#{port}" unless @enabled
+
+      query = URI.encode_www_form('key' => @key_path, 'cert' => @cert_path)
+      "ssl://#{h}:#{port}?#{query}"
+    end
+
+    def scheme
+      @enabled ? 'https' : 'http'
+    end
+
+    # Expiry (not_after) of the configured certificate, or nil if it cannot be
+    # read/parsed. Used to surface silent-expiry breakage at startup.
+    def certificate_not_after
+      return nil unless @cert_path && File.exist?(@cert_path)
+
+      OpenSSL::X509::Certificate.new(File.read(@cert_path)).not_after
+    rescue StandardError
+      nil
+    end
+
+    # Whole days until the certificate expires (negative if already expired),
+    # or nil if the cert cannot be read. now is injectable for testing.
+    def days_until_expiry(now = Time.now)
+      not_after = certificate_not_after
+      return nil unless not_after
+
+      ((not_after - now) / 86_400).floor
+    end
+
+    private
+
+    # An IPv6 literal host must be bracketed in a URI authority
+    # (ssl://[::1]:8443), otherwise Puma's binder misparses the colons.
+    def bracket_ipv6(host)
+      s = host.to_s
+      return s if s.empty? || s.start_with?('[') || !s.include?(':')
+
+      "[#{s}]"
+    end
+
+    def present_or(value, default)
+      s = value.to_s.strip
+      s.empty? ? default : s
+    end
+
+    def resolve(path)
+      return nil if path.nil? || path.to_s.empty?
+
+      File.absolute_path?(path) ? path : File.join(@data_dir, path)
+    end
+
+    def safe_parse
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+
+  # Raised when TLS is enabled but its material cannot be located or used.
+  class TlsConfigError < StandardError; end
+end

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.39.0"
+  VERSION = "3.40.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/knowledge/kairoschain_setup/kairoschain_setup.md

@@ -654,7 +654,10 @@ Options:
     --data-dir DIR  Data directory path (default: .kairos/ in current dir)
     --http          Start in Streamable HTTP mode (default: stdio)
     --port PORT     HTTP port (default: 8080)
-    --host HOST     HTTP bind host (default: 0.0.0.0)
+    --host HOST     HTTP bind host (default: config http.host, else 127.0.0.1)
+    --tls           Enable built-in TLS/HTTPS (requires a cert — see --gen-cert)
+    --gen-cert      Generate a self-signed TLS cert/key and exit
+    --cert-host HOST  Add a hostname/IP to the generated cert SAN (repeatable)
     --init-admin    Generate initial admin token and exit
     --token-store PATH  Path to token store file
     -v, --version   Show version
@@ -662,11 +665,41 @@ Options:
 
 Environment Variables:
     KAIROS_DATA_DIR   Override data directory path
+    KAIROS_ALLOW_OPEN_ENDPOINT  Set to 1 to start without a token on a network-reachable bind (unsafe)
 ```
 
-#### Production Deployment with HTTPS
+#### HTTPS / TLS
 
-For production use, place a reverse proxy in front of Puma to handle TLS/HTTPS. Puma only handles plain HTTP internally; the reverse proxy terminates SSL.
+There are two ways to serve the MCP endpoint over TLS. Encryption is always performed by
+Puma/OpenSSL — KairosChain only selects the transport (plain HTTP vs TLS).
+
+**Option A: Built-in TLS (single operator / remote access)**
+
+KairosChain can terminate TLS itself, so a self-hosted instance can be reached securely
+without a separate proxy.
+
+```bash
+# 1. Generate a self-signed cert/key once (written to <data-dir>/storage/tls/).
+#    Include every hostname/IP you connect by, so certificate verification passes:
+kairos-chain --gen-cert --cert-host myhost.example.com
+
+# 2. Start with TLS (or set http.tls.enabled: true in skills/config.yml):
+kairos-chain --http --tls
+```
+
+Notes:
+- The certificate is self-signed, so the client (Cursor / Claude Code) must trust it
+  (or disable verification). For a CA-issued certificate, use Option B.
+- Certificates expire (default ~2 years). The server logs the expiry at startup and
+  warns when it is near; regenerate by deleting the old cert and running `--gen-cert` again.
+- If no admin token is configured, KairosChain refuses to start on a network-reachable
+  bind (that would be an open owner endpoint). Run `--init-admin` first, or set
+  `KAIROS_ALLOW_OPEN_ENDPOINT=1` to start without authentication intentionally.
+
+**Option B: Reverse proxy (public / multi-user)**
+
+For a public or multi-user deployment, place a reverse proxy in front of Puma; the proxy
+terminates TLS with a CA-issued certificate.
 
 ```
 Client (Cursor) ──HTTPS──▶ Reverse Proxy ──HTTP──▶ Puma (:8080)
@@ -674,7 +707,7 @@ Client (Cursor) ──HTTPS──▶ Reverse Proxy ──HTTP──▶ Puma (:80
                            TLS termination
 ```
 
-**Option A: Caddy (Recommended — Simplest)**
+**Caddy (Recommended — Simplest)**
 
 Caddy provides automatic HTTPS with Let's Encrypt certificates (zero configuration for TLS).
 

data/templates/knowledge/kairoschain_setup_jp/kairoschain_setup_jp.md

@@ -638,7 +638,10 @@ Usage: kairos-chain [command] [options]
     --data-dir DIR  データディレクトリのパス（デフォルト: カレントディレクトリの .kairos/）
     --http          Streamable HTTPモードで起動（デフォルト: stdio）
     --port PORT     HTTPポート（デフォルト: 8080）
-    --host HOST     HTTPバインドホスト（デフォルト: 0.0.0.0）
+    --host HOST     HTTPバインドホスト（デフォルト: config の http.host、無ければ 127.0.0.1）
+    --tls           内蔵TLS/HTTPSを有効化（証明書が必要 — --gen-cert を参照）
+    --gen-cert      自己署名のTLS証明書/鍵を生成して終了
+    --cert-host HOST  生成する証明書のSANにホスト名/IPを追加（繰り返し指定可）
     --init-admin    初期管理者トークンを生成して終了
     --token-store PATH  トークンストアファイルのパス
     -v, --version   バージョン表示
@@ -646,11 +649,34 @@ Usage: kairos-chain [command] [options]
 
 環境変数:
     KAIROS_DATA_DIR   データディレクトリのパスを上書き
+    KAIROS_ALLOW_OPEN_ENDPOINT  1 にすると、ネットワーク到達可能なバインドでもトークン無しで起動（危険）
 ```
 
-#### 本番環境でのHTTPSデプロイ
+#### HTTPS / TLS
 
-本番運用では、Pumaの前段にリバースプロキシを配置してTLS/HTTPSを処理します。Puma内部はプレーンHTTPのみを処理し、リバースプロキシがSSLを終端します。
+MCPエンドポイントをTLSで提供する方法は2つあります。暗号化は常に Puma/OpenSSL が行い、KairosChain は通信路（平文HTTP か TLS か）を選ぶだけです。
+
+**オプションA: 内蔵TLS（単独運用者 / 遠隔アクセス）**
+
+KairosChain は自分でTLSを終端できるので、別途プロキシを立てなくても自ホストのインスタンスに安全に接続できます。
+
+```bash
+# 1. 自己署名の証明書/鍵を一度だけ生成（<data-dir>/storage/tls/ に出力）。
+#    接続に使うホスト名/IPを含めておくと、証明書の検証が通ります:
+kairos-chain --gen-cert --cert-host myhost.example.com
+
+# 2. TLSで起動（または skills/config.yml で http.tls.enabled: true を設定）:
+kairos-chain --http --tls
+```
+
+補足:
+- 証明書は自己署名なので、クライアント（Cursor / Claude Code）側で信頼する（または検証を無効化する）必要があります。認証局発行の証明書が必要な場合はオプションBを使ってください。
+- 証明書には有効期限（既定で約2年）があります。サーバは起動時に期限を記録し、期限が近いと警告します。更新は、古い証明書を削除して `--gen-cert` を再実行します。
+- 管理者トークンが未設定の場合、ネットワーク到達可能なバインドでは起動を拒否します（無認証のowner露出になるため）。先に `--init-admin` を実行するか、意図的に無認証で起動する場合は `KAIROS_ALLOW_OPEN_ENDPOINT=1` を設定します。
+
+**オプションB: リバースプロキシ（公開 / マルチユーザー）**
+
+公開・マルチユーザー運用では、Pumaの前段にリバースプロキシを配置します。プロキシが認証局発行の証明書でTLSを終端します。
 
 ```
 クライアント (Cursor) ──HTTPS──▶ リバースプロキシ ──HTTP──▶ Puma (:8080)
@@ -658,7 +684,7 @@ Usage: kairos-chain [command] [options]
                                  TLS終端
 ```
 
-**オプションA: Caddy（推奨 — 最もシンプル）**
+**Caddy（推奨 — 最もシンプル）**
 
 CaddyはLet's Encrypt証明書による自動HTTPS（TLSの設定不要）を提供します。
 

data/templates/skills/config.yml

@@ -190,6 +190,21 @@ http:
   token_store: "storage/tokens.json"      # Token storage path (uses SQLite if backend is sqlite)
   default_token_expiry_days: 90           # Default token expiry (days)
 
+  # -----------------------------------------------------------------------
+  # TLS (HTTPS) — optional transport encryption for remote access
+  # -----------------------------------------------------------------------
+  # Encryption is delegated to Puma/OpenSSL; KairosChain only selects the
+  # bind scheme (Prop 2: transport is execution substrate, not core logic).
+  # For a single operator, generate a self-signed cert once, then enable:
+  #     kairos-chain --gen-cert
+  #     kairos-chain --http --tls        # or set enabled: true below
+  # For a public service, prefer a reverse proxy (e.g. Caddy) with a
+  # CA-issued certificate instead of a self-signed cert.
+  tls:
+    enabled: false                        # opt-in; false = plain HTTP (default)
+    cert: "storage/tls/cert.pem"          # certificate path (relative to data dir)
+    key:  "storage/tls/key.pem"           # private key path (chmod 0600)
+
   # -----------------------------------------------------------------------
   # Phase 2 (Future): Role-Based Authorization
   # -----------------------------------------------------------------------

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.39.0
+  version: 3.40.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -172,6 +172,8 @@ files:
 - lib/kairos_mcp/storage/file_backend.rb
 - lib/kairos_mcp/storage/importer.rb
 - lib/kairos_mcp/storage/sqlite_backend.rb
+- lib/kairos_mcp/tls_cert_generator.rb
+- lib/kairos_mcp/tls_config.rb
 - lib/kairos_mcp/tool_registry.rb
 - lib/kairos_mcp/tools/base_tool.rb
 - lib/kairos_mcp/tools/capability_status.rb