kairos-chain 3.35.0 → 3.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 790cf38c2263e065c856211e0dce54a56a4e9599b2b028dbd3335405f78d069f
-  data.tar.gz: 3a568dc9d900c4aefc24572657043c82d94ea62027a349f6c3e20094d778cbb7
+  metadata.gz: 2285b28e2f2954ca10f6da869b7446b4d18fdc0f9174451f20ec8f523142b322
+  data.tar.gz: 9a14c47fd141de6ff7eaec10d6e56c44f01e96b1cb0b9ab962eedb4baccc8e4b
 SHA512:
-  metadata.gz: a3d7d364ecfe3512de1ca75375eefe890002b4c228f7dd3245ea00277abe1552030261a3916ef27ec3c1e968381646ac73a0811672016a8d16d6fab282954c31
-  data.tar.gz: 1bc3370f34c14841d0b57c471ff9e71185521bfe36b583c788732f6513d453c619a07e53070bb6e4d674b6b3b2ae4ec716663f53247d65e9a380a968e942752c
+  metadata.gz: 89a5a8a47b38f8f703283c58d9e402efeab1a2124fa1ad2195c0820edd985301ce68b22dd40012614499d09f9b34410905e473ca33ccad97e8d32d804ba46eb1
+  data.tar.gz: df15f0d5f6cdb22039840cf780b235cba8194e77da2738478b37dbeb446c25814609887083566388bae2abeb2f067e0aa2ecb24d16b4ca626b75644818d794eb

data/CHANGELOG.md

@@ -4,6 +4,166 @@ 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
+
+Adds a pre-draft unknown-discovery discipline to the multi-LLM review workflow,
+adapted from Thariq Shihipar's "A Field Guide to Fable: Finding Your Unknowns"
+(2026-07-03), techniques ① blindspot pass and ③ one-question-at-a-time interview.
+Bundled L1 knowledge only — no code paths changed.
+
+- **Step 0.25 (pre-draft, qualifying reviews only)**: before drafting a design or
+  knowledge/documentation artifact routed to full multi-LLM review, the orchestrator
+  enumerates its blind-spot questions (without self-answering) and interviews the human
+  one question at a time, then triages every surfaced unknown to Resolved / Declared /
+  Draft-deferred. Moves unknown discovery from the expensive channel (review rounds) to
+  the cheap channel (pre-draft dialogue).
+- **Five invariants INV-U1–U5**: front-load gate (no dispatch before the pass);
+  human gate (no orchestrator self-answering); constitutive recording (unconditional L2
+  record, incl. zero-result); bounded demotion of declared unknowns (provenance bound +
+  inverted default, closing a laundering channel); human-only classification authority.
+- **Unattended (autonomous loop) clause**: fail-closed — every surfaced unknown is
+  judgment-shaped by default and stops the run; only a human-authored mandate may
+  pre-classify categories as non-judgment-shaped, and unattended declarations gain no
+  reviewer-demotion power until human-ratified. Mandate expressiveness, ratification
+  protocol, and the pending-question queue are deferred to the Autonomous Growth Loop
+  guard track.
+- Three-location L1 sync (instance `.kairos/knowledge/`, gem `knowledge/`, gem
+  `templates/knowledge/`); change recorded to blockchain (hash a74a11b7…). One-line
+  cross-reference added to `design_to_implementation_workflow`.
+- Designed via its own 3-round self-referential multi-LLM review (R1 REVISE 2/6 →
+  R2 REVISE 2/6 → R3 4/6 APPROVE; design record
+  `docs/drafts/multi_llm_review_unknowns_pass_v0.3.1_FROZEN.md`).
+
+## [3.38.0] - 2026-07-05
+
+### Added — Synoptis L2 attestation: ACT-5 trigger sources + scan CLI (Slice 3b/3c)
+
+Makes the ACT-5 trigger point distinguishable and invocable from a session-end
+Stop hook, so firing + trigger-record logging can be guaranteed rather than relying
+on the orchestrator remembering to run the tool.
+
+- **Trigger source (3b)**: `l2_attestation_scan` gains a `trigger_source` argument
+  (`manual` / `orchestrator_session_end` / `session_end_hook`), recorded in the trigger
+  record (`AttestationChain#append_trigger(source:)`). ACT-5's "at least one defined
+  trigger point" is now distinguishable in the operational log, and the tool documents
+  its two auto-firing paths (orchestrator-at-session-end for delivery+approval; Stop hook
+  for a mechanical liveness guarantee).
+- **Scan CLI (3c)**: new `kairos-chain attestation scan [--session SID] [--source SRC]
+  [--data-dir DIR]`. It loads the constitutive criterion, proposes a session's
+  judgment-bearing contexts, and appends a trigger record — propose-only, never attests
+  (ACT-1 keeps attestation human-approved through the MCP tool). This is the shell
+  entry point a session-end Stop hook calls. Verified end-to-end.
+
+The two firing mechanisms are complementary: the orchestrator convention delivers
+proposals to a present human for approval; the Stop hook guarantees the trigger fires
+and is logged even when the orchestrator does not. The settings.json Stop-hook wiring is
+a per-project harness step (not shipped in the gem). 17 Slice-3 unit tests green (incl.
+trigger-source); Slices 1 (35) and 2 (25) unchanged.
+
+## [3.37.0] - 2026-07-05
+
+### Added — Synoptis L2 attestation: semantic criterion + snapshot (Slice 3a)
+
+Matures the ACT-2 selection criterion and adds the optional content snapshot
+(§Kinds), without embedding an LLM call inside the tool (selective-survival: the
+in-Ruby LLM scoring is deferred until the frontmatter criterion is observed to be
+insufficient).
+
+- **Semantic layer (ACT-2)**: `l2_attestation_scan` now attaches a bounded content
+  `preview` to each proposal and surfaces a `rubric` (config `semantic_rubric`). The
+  orchestrator applies the rubric to the previews to decide which frontmatter-filtered
+  candidates to propose to the human — the LLM-semantic judgment lives in the
+  orchestrator, not in the tool. The criterion stays inspectable and revisable by
+  editing config (`judgment_types`, `semantic_rubric`, `preview_chars`).
+- **Snapshot (§Kinds optional)**: `l2_attestation_commit(embed_snapshot: true)` embeds
+  the subject's current content in the entry, so audits needing the original wording
+  have it (LED-2a preserves it). The snapshot's SHA256 equals the entry digest, so it is
+  self-verifying. Bounded by `max_snapshot_bytes` (default 256KB); oversize content is
+  refused (`snapshot_too_large`) rather than truncated.
+- `SubjectRef` gains `content_text` / `content_preview`.
+
+Deferred (until observed need): in-Ruby `llm_client` scoring of candidates; session-end
+auto-firing of the trigger (ACT-5 liveness is currently satisfied by explicit/orchestrator
+scan). 12 Slice-3 unit tests + 4 tool integration tests green; Slices 1 (35) and 2 (25)
+unchanged.
+
+## [3.36.0] - 2026-07-05
+
+### Added — Synoptis L2 attestation: supersession + revocation (Slice 2)
+
+Records the rewrite/withdrawal lifecycle of a constitutive attestation by appending,
+never editing (the bank-ledger correction model). Completes §Kinds' two attestation-
+ledger entry kinds and satisfies LED-2b (lineage) and ACT-3 (approval binding).
+
+- **Supersession**: a re-attestation of an already-attested subject is now a
+  supersession — `l2_attestation_commit` auto-derives the current head and commits its
+  entry_id as `target_ref` (ContentAttestationEntry gains `target_ref`). The first
+  attestation about a subject carries none.
+- **Revocation-withdrawal**: new `RevocationWithdrawalEntry` kind (commits subject +
+  target_ref + moment, no digest/content) and a new `l2_attestation_revoke` tool. It
+  appends a withdrawal of the subject's current head; like any ledger entry it requires
+  human approval (ACT-1) and is itself append-only, so "claimed then withdrawn" survives.
+- **ACT-3 binding**: the commit/revoke proposal returns the digest and the target it
+  would act on; the approving call echoes them as `expected_digest` /
+  `expected_target_ref`. If the live content changed (digest_mismatch) or the head moved
+  (target_moved) between proposal and approval, the append is refused, not silent.
+- **Fold**: `AttestationChain#current_head` / `current_state` fold a subject's entries
+  (first → supersessions → withdrawals) into a status (none/attested/withdrawn); a new
+  read-only `l2_attestation_view` tool surfaces it. Fold ordering rule fixed per §11: a
+  revocation clears the head only when it targets the current head.
+
+Synoptis's trust engine (duplicate hard-reject, TTL, revocation store) is untouched —
+the constitutive ledger is a separate chain, so re-attest-as-supersession is native and
+no reconciliation was needed. 25 Slice-2 unit tests + 14 tool integration tests green;
+Slice 1 (35) unchanged.
+
+## [3.35.1] - 2026-07-05
+
+### Fixed — Synoptis L2 attestation: frontmatter parsing dropped all proposals
+
+`l2_attestation_scan` surfaced zero proposals against real L2 contexts because
+`SubjectRef.extract_frontmatter` used `YAML.safe_load` without permitting `Date`:
+a `date:` field (present in every real context's frontmatter) raised
+`Psych::DisallowedClass`, which was rescued to `nil`, so the `type` was never read
+and no context matched the criterion. Caught by live end-to-end verification, not
+by unit tests (whose fixtures lacked a `date:` field). Fix permits `[Date, Time]`
+and adds a regex fallback for the single `type` scalar so the criterion is robust
+against any frontmatter YAML that `safe_load` rejects. Unit fixtures now carry a
+`date:` field to guard the regression.
+
 ## [3.35.0] - 2026-07-05
 
 ### Added — Synoptis: L2 constitutive attestation (Slice 1)

data/bin/kairos-chain

@@ -343,6 +343,86 @@ when 'upgrade'
   end
   exit
 
+when 'attestation'
+  # Constitutive L2 attestation CLI (Slice 3c). Currently one action: `scan`, the
+  # ACT-5 trigger point invokable from a session-end Stop hook so that firing +
+  # trigger-record logging is guaranteed even when the orchestrator does not run the
+  # MCP tool. It proposes only and logs a trigger record; it never attests (ACT-1
+  # keeps attestation human-approved through the MCP tool).
+  ARGV.shift # Remove 'attestation'
+
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+  require 'kairos_mcp'
+
+  if (idx = ARGV.index('--data-dir'))
+    KairosMcp.data_dir = File.expand_path(ARGV[idx + 1])
+    ARGV.delete_at(idx + 1)
+    ARGV.delete_at(idx)
+  end
+
+  action = ARGV.shift
+  case action
+  when 'scan'
+    require 'json'
+    require 'yaml'
+    require 'fileutils'
+
+    session = (i = ARGV.index('--session')) ? ARGV[i + 1] : nil
+    source  = (i = ARGV.index('--source')) ? ARGV[i + 1] : 'session_end_hook'
+
+    syn_lib = File.join(KairosMcp.skillsets_dir, 'synoptis', 'lib')
+    unless File.directory?(syn_lib)
+      puts JSON.generate(status: 'error', message: 'synoptis skillset not installed')
+      exit 0
+    end
+    $LOAD_PATH.unshift(syn_lib)
+    require 'synoptis/registry/file_registry'
+    require 'synoptis/constitutive/subject_ref'
+    require 'synoptis/constitutive/proposal_criterion'
+    require 'synoptis/constitutive/attestation_chain'
+
+    context_dir = KairosMcp.context_dir
+    session ||= if Dir.exist?(context_dir)
+                  Dir.children(context_dir)
+                     .select { |c| File.directory?(File.join(context_dir, c)) }
+                     .max_by { |c| File.mtime(File.join(context_dir, c)) }
+                end
+    unless session
+      puts JSON.generate(status: 'error', message: 'no session found to scan')
+      exit 0
+    end
+
+    cfg_path = File.join(KairosMcp.skillsets_dir, 'synoptis', 'config', 'synoptis.yml')
+    const_cfg = (File.exist?(cfg_path) ? (YAML.safe_load(File.read(cfg_path)) || {}) : {})['constitutive'] || {}
+
+    data_dir = File.join(KairosMcp.data_dir, 'synoptis_data')
+    FileUtils.mkdir_p(data_dir)
+    registry = Synoptis::Registry::FileRegistry.new(data_dir: data_dir)
+    chain = Synoptis::Constitutive::AttestationChain.new(registry: registry)
+    criterion = Synoptis::Constitutive::ProposalCriterion.new(
+      context_dir: context_dir,
+      judgment_types: const_cfg['judgment_types'] ||
+        Synoptis::Constitutive::ProposalCriterion::DEFAULT_JUDGMENT_TYPES,
+      preview_chars: const_cfg['preview_chars'] ||
+        Synoptis::Constitutive::ProposalCriterion::DEFAULT_PREVIEW_CHARS
+    )
+
+    proposals = criterion.propose(session_id: session)
+    chain.append_trigger(surfaced_count: proposals.length, source: source)
+    puts JSON.generate(
+      status: 'proposed',
+      session_id: session,
+      trigger_source: source,
+      surfaced_count: proposals.length,
+      proposals: proposals
+    )
+    exit 0
+  else
+    warn "Unknown attestation action: #{action.inspect}"
+    warn 'Usage: kairos-chain attestation scan [--session SID] [--source SRC] [--data-dir DIR]'
+    exit 1
+  end
+
 when 'mode'
   ARGV.shift # Remove 'mode' from ARGV
 
@@ -556,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
@@ -635,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'
@@ -654,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
@@ -710,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 "    }"
@@ -737,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