terret-core 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb6dbfe91797674f464068e08da10eb0d19289dc30d3a791c5c46d9450c9ff13
-  data.tar.gz: fa2cabe0f12d5fe1a94d9d14cb22686f9e6208dfd9b5a69316124ee1bf162ee5
+  metadata.gz: f36dbce70ed5b476d44ca902a7a261d7ae71c0f019109f9ec02052f8c7900714
+  data.tar.gz: c149aa846c4ea730562fa0e2f3e0539edc12ba533f468bac578f19617ef903ad
 SHA512:
-  metadata.gz: c4cfee58e20514fdeb1e8f3d60e3336916c6c54e169377f1ff64ec1ba1d6373b6dc2a2a01c7f579ede66d0f49a92fc90151947910b9a4bfe5e895dca3ab4b426
-  data.tar.gz: c250f6994e87dc668bd6cc60d9e967ff8f1232b972cb0be4853c4c0ba9a257012450424701d93fc13b39106e2dbcb63d3cddf55abccfa5a4ec2ed9bd31a8a2ba
+  metadata.gz: 83921151858e5edf9df27f6a7a6064d2936f5059fc504e6ffd27e469ed345c516504c88f7c7104309ba238063bf403a718d1cbbf33f64ea85313e656e618c3f5
+  data.tar.gz: 64f2129e36d07a74d1cbd4a0caf49763519992992398f634e2383c3d0439abb8c51119be93fbb4399c5823305ca97270f0884d1072d2cf9a2a20fdc1be15a30f

data/lib/terret/approvals.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Terret
+  module Tools
+    # ctx[:approvals] — durable human-in-the-loop gating (plan §6.3, §12 M6).
+    # An execute-stage middleware parks calls whose definition demands a
+    # decision, appends durable approval/requested, and resumes when a
+    # matching approval/resolved lands in the log (the socket's approve/deny
+    # frames append exactly that). Both sides are durable, so a parked call
+    # survives a process death: on resume the gate finds the recorded verdict
+    # and never parks. It gates on tools/execute rather than tools/pre_execute
+    # so pre_execute vetoes (the per-agent AllowList) settle a call before a
+    # human is ever asked.
+    class Approvals < Hames::Service
+      service_key :approvals
+      inject :sessions, :tools, :loop
+      config_schema({}) # opt-in per tool; the service itself takes no config
+
+      def start(ctx)
+        @ctx = ctx
+        # A unique per-park token => { session_id:, call_id:, queue: }. Keyed by
+        # the token rather than by [session_id, call_id] because provider
+        # tool-call ids are NOT contractually unique: two calls of one parallel
+        # batch can arrive sharing an id, and keying by it let the second park
+        # overwrite the first's queue so a single verdict woke only the survivor
+        # and the first fiber parked forever, hanging the barrier. Each park now
+        # owns its own entry and its own wake. The DURABLE correlation
+        # (approval/requested and /resolved, matched in the log on call_id +
+        # name + args) is unchanged; only this in-memory map needed unique keys.
+        @waiting = {}
+        @waiting_mutex = Mutex.new # tests resolve from another thread; wake_one scans
+        @park_seq = 0
+
+        ctx.on("tools/execute") do |call, next_|
+          gate(call, next_)
+        end
+        ctx.on("session/event") do |ev|
+          next unless ev.type == "approval/resolved"
+
+          wake_one(ev.session_id, ev.payload[:call_id], ev.payload)
+        end
+      end
+
+      # Log-derived: requested without a matching resolved, within the OPEN
+      # turn. The in-memory waiter map is never consulted — after a restart it
+      # is empty while the log still knows what is owed. Nothing is pending
+      # once the turn that asked has closed: a request its turn outlived was
+      # settled by that turn ending, and a provider is free to reuse the call
+      # id afterwards.
+      def pending(session_id)
+        events = open_turn(session_id)
+        resolved = events.filter_map { |e| e.payload[:call_id] if e.type == "approval/resolved" }
+        events.filter_map do |e|
+          next unless e.type == "approval/requested"
+          next if resolved.include?(e.payload[:call_id])
+
+          e.payload[:call_id]
+        end
+      end
+
+      def pending?(session_id, call_id) = pending(session_id).include?(call_id)
+
+      # Cancel's escape hatch: deny everything parked for a session, durably.
+      # Each denial is an ordinary approval/resolved append, so an in-process
+      # parked fiber unparks through the same listener as a socket verdict,
+      # and a restart-orphaned request settles for good.
+      def deny_pending!(session_id, reason: "cancelled")
+        pending(session_id).each do |call_id|
+          @ctx[:sessions].append(session_id, "approval/resolved",
+                                 { call_id: call_id, verdict: "denied", reason: reason })
+        end
+        # The durable denials above wake one waiter per unique pending id
+        # through the resolved listener. A provider that reused a call id within
+        # one parallel batch parked more than one fiber on that id, though, and
+        # a cancel means all of them: sweep whatever is still parked for this
+        # session onto the denial they share, so no fiber is left holding the
+        # barrier open. Waiters the appends already woke are gone from the map,
+        # so this touches only the ones a single durable denial could not reach.
+        drain_session_waiters(session_id, { verdict: "denied", reason: reason })
+      end
+
+      private
+
+      def gate(call, next_)
+        d = begin
+          @ctx[:tools].fetch(call.name)
+        rescue KeyError
+          nil # vanished tool: fall through — the base renders its recoverable error
+        end
+        return next_.(call) unless d && requires_approval?(d)
+
+        # Order is the contract: a verdict already in the log settles the call
+        # however it got there, so a resume inside a child honors the decision
+        # a human really made. Only a call with no answer at all reaches the
+        # unattended check, and only then does it fail closed.
+        verdict = recorded_verdict(call) || unattended_verdict(call) || park(call)
+        if verdict[:verdict] == "approved"
+          next_.(call)
+        else
+          reason = verdict[:reason] || "no reason given"
+          Result.new(id: call.id, content: nil, error: "#{call.name} denied: #{reason}")
+        end
+      end
+
+      # Fail closed instead of deadlocking. A subagent's session cannot be
+      # reached by any approver: the parent's log never names it, so no socket
+      # is bound to it and no operator can answer a request they were never
+      # shown. Parking there would wait on a verdict that cannot arrive and
+      # would take the parent's turn — and the fiber running it — with it, so
+      # the call is denied with a reason the model can act on and report.
+      #
+      # Nothing durable is appended for the refusal. It is not a decision
+      # anybody made, and the tool/result the loop writes is already the
+      # permanent record of what happened to the call.
+      UNATTENDED_DENIAL = { verdict: "denied",
+                            reason: "no approver can reach a subagent session" }.freeze
+
+      def unattended_verdict(call)
+        agent = @ctx[:loop].agent_for_session(call.session_id)
+        agent&.unattended ? UNATTENDED_DENIAL : nil
+      end
+
+      # :always asks every time; :policy asks when the tool mutates (plan
+      # §13's spirit: mutation is what needs a human under policy); :never
+      # (the default) passes through.
+      def requires_approval?(d)
+        d.approval == :always || (d.approval == :policy && d.mutating)
+      end
+
+      # Everything appended after the last turn/start, and nothing at all once
+      # that turn has closed. Approvals are per-turn state.
+      def open_turn(session_id)
+        events = @ctx[:sessions].fetch(session_id).events
+        opened = events.rindex { |e| e.type == "turn/start" }
+        return [] unless opened
+
+        turn = events[(opened + 1)..]
+        turn.any? { |e| e.type == "turn/end" } ? [] : turn
+      end
+
+      # A verdict already in the log (replay after a restart, or a decision
+      # that raced ahead of execution) settles the call without parking. The
+      # match is bound to content, not just to the call id: the latest request
+      # in the open turn naming this id, this tool, and these args, with a
+      # verdict for that id recorded after it. Provider tool call ids are not
+      # contractually unique, so an id reused in a later turn — or reused
+      # within one turn for a different call — must never inherit an old
+      # decision.
+      def recorded_verdict(call)
+        events = open_turn(call.session_id)
+        # Both compared in stored form, and hoisted out of the scan: a tool
+        # name is content like its args (the model chooses it), so a scrubber
+        # rewrites it on the way into the log and a raw comparison would never
+        # match again.
+        name = stored_form(call.name)
+        args = stored_form(call.args)
+        asked = events.rindex do |e|
+          e.type == "approval/requested" && e.payload[:call_id] == call.id &&
+            e.payload[:name] == name && e.payload[:args] == args
+        end
+        return nil unless asked
+
+        events[(asked + 1)..].find do |e|
+          e.type == "approval/resolved" && e.payload[:call_id] == call.id
+        end&.payload
+      rescue NonPrimitivePayload
+        # A value the log refuses has no stored form to compare against — a
+        # Time or some other object a plugin synthesized into args, which the
+        # JSON round trip this used to do coerced silently. That is a
+        # comparison this method cannot make, not a verdict it found, so it
+        # answers nil and the call parks. Park re-uses a standing request where
+        # there is one; with no standing request, park's own append of these
+        # same args raises there instead — which is what this path has always
+        # done with a value the log cannot store, and is left alone. Provider
+        # args are JSON primitives, so a model's own call never reaches here.
+        nil
+      end
+
+      # Args reach the log through Sessions' primitives contract (symbol keys,
+      # symbols in value position stringified) AND through any registered
+      # scrubber, so the comparison above is against what was really stored.
+      # Asking Sessions rather than round-tripping JSON here is what keeps a
+      # redacted argument from making an approved call ask a second time:
+      # every rewrite the append applies has to be applied to this side too.
+      def stored_form(args) = @ctx[:sessions].stored_form(args)
+
+      def park(call)
+        q = Thread::Queue.new
+        token = nil
+        # waiter first, then the durable request: a verdict can never land in
+        # the gap between the append's fan-out and the waiter existing
+        @waiting_mutex.synchronize do
+          token = (@park_seq += 1)
+          @waiting[token] = { session_id: call.session_id, call_id: call.id, queue: q }
+        end
+        # ...and the gate's own lookup happened before that waiter existed, so
+        # a verdict landing in between signalled nothing. Look again now that
+        # a signal has somewhere to land, or the pop below waits forever.
+        if (raced = recorded_verdict(call))
+          return raced
+        end
+
+        agent = @ctx[:loop].agent_for_session(call.session_id)
+        unless pending?(call.session_id, call.id) # a resume re-parks on the standing request
+          @ctx[:sessions].append(call.session_id, "approval/requested",
+                                 { call_id: call.id, name: call.name, args: call.args })
+        end
+        agent&.status = :waiting_approval
+        # cooperative under the fiber scheduler (parks the fiber); blocks the
+        # thread under plain minitest, where tests resolve from another thread
+        q.pop
+      ensure
+        @waiting_mutex.synchronize { @waiting.delete(token) } if token
+        restore(agent, call.session_id)
+      end
+
+      # Wake exactly one waiter parked on this (session, call_id). One durable
+      # verdict is one decision, so it releases one park; a second verdict for a
+      # reused id releases the next. FIFO by insertion, so the call that parked
+      # first is the first one a verdict frees.
+      def wake_one(session_id, call_id, payload)
+        entry = @waiting_mutex.synchronize do
+          token, e = @waiting.find do |_t, w|
+            w[:session_id] == session_id && w[:call_id] == call_id
+          end
+          @waiting.delete(token) if token
+          e
+        end
+        entry && entry[:queue].push(payload)
+      end
+
+      # Release every waiter still parked for a session onto one payload — the
+      # cancel path's escape hatch (deny_pending!), so a reused call id cannot
+      # leave a fiber holding the barrier open after the durable denials ran.
+      def drain_session_waiters(session_id, payload)
+        entries = @waiting_mutex.synchronize do
+          matched = @waiting.select { |_t, w| w[:session_id] == session_id }
+          matched.each_key { |t| @waiting.delete(t) }
+          matched.values
+        end
+        entries.each { |e| e[:queue].push(payload) }
+      end
+
+      # What the agent goes back to when a parked call comes out, derived from
+      # the LOG rather than from the label this park overwrote.
+      #
+      # A parallel run can park two calls at once (docs/subagents.md §5), and
+      # the fiber that unparks first must not announce a turn that is still
+      # waiting on a human: the socket reads this status to decide whether a
+      # cancel also has to deny_pending!, so a premature :running is a turn
+      # nobody can cancel and a sibling parked forever. While anything is
+      # still pending for the session, :waiting_approval stays true.
+      #
+      # And the restore that does happen is decided rather than left to
+      # whichever assignment runs last: a cancel requested while the call was
+      # parked has not stopped being true just because a verdict landed, so
+      # the fiber unparks into a turn that already knows it is stopping and
+      # the status says the same thing (docs/subagents.md §8).
+      def restore(agent, session_id)
+        return unless agent && agent.status == :waiting_approval
+        return unless pending(session_id).empty?
+
+        agent.status = agent.cancelled? ? :stopping : :running
+      end
+    end
+  end
+end

data/lib/terret/compactor.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Terret
+  # ctx[:compactor] — turns a long history into a short one without breaking
+  # "model-visible means logged" (§2.5): the summary is itself a durable
+  # event, and derive_messages projects it in place of everything at or
+  # before its boundary. The §12 contract: upto_seq is ALWAYS the seq
+  # immediately preceding the compaction event — the projection prepends the
+  # summary, so any gap would interleave it among events that predate it.
+  # The boundary is computed at append time, after the summarizer returns:
+  # only projection-invisible events can land during summarization (the
+  # agent is still mid-turn, so nothing model-visible can interleave).
+  #
+  # Summary GENERATION is a seam: ctx[:summarizer] (sole provider, like the
+  # session store). A summarizer may decline by returning nil/empty —
+  # compaction is an optimization, so a decline warns and the next
+  # overweight turn retries. A summarizer that raises inside the trigger is
+  # isolated by emit dispatch; a manual compact! raises through.
+  class Compactor < Hames::Service
+    service_key :compactor
+    inject :sessions, :summarizer
+    config_schema budget: { type: Integer,
+                            doc: "token budget that triggers compaction; unset or falsy disables it" }
+
+    def start(ctx)
+      @ctx = ctx
+      @budget = config[:budget]
+      # Always registered, gated at fire time: a hot-set budget (reconfigure)
+      # arms the trigger without a remount.
+      ctx.on("session/event") do |ev|
+        next unless @budget && ev.type == "turn/end"
+
+        compact!(ev.session_id) if overweight?(ev.session_id)
+      end
+    end
+
+    def reconfigure(config)
+      @budget = config[:budget]
+    end
+
+    # Everything derive_messages projects. Anything else may land under a
+    # boundary without being summarized; these may not.
+    MODEL_VISIBLE = %w[user/message context/injected assistant/message
+                       tool/result session/compacted].freeze
+
+    # Summarize the whole projected history and append the boundary event.
+    # Returns the appended SessionEvent, or nil when the summarizer declined.
+    def compact!(session_id)
+      sessions = @ctx[:sessions]
+      history = sessions.derive_messages(session_id)
+      raise ArgumentError, "nothing to compact in #{session_id}" if history.empty?
+
+      base_seq = sessions.fetch(session_id).events.last.seq
+      summary = @ctx[:summarizer].summarize(history)
+      unless summary.is_a?(String) && !summary.strip.empty?
+        warn "terret: compaction skipped for #{session_id}: summarizer declined"
+        return nil
+      end
+
+      # Summarizing is a round trip; the boundary covers the whole prefix, so
+      # model-visible history arriving while it ran would be swept under a
+      # summary that never read it. Decline instead — the next overweight turn
+      # retries, and nothing is lost in the meantime.
+      raced = sessions.fetch(session_id).events
+                      .count { |e| e.seq > base_seq && MODEL_VISIBLE.include?(e.type) }
+      unless raced.zero?
+        warn "terret: compaction skipped for #{session_id}: " \
+             "#{raced} model-visible event(s) landed while summarizing"
+        return nil
+      end
+
+      sessions.append(session_id, "session/compacted",
+                      { upto_seq: sessions.fetch(session_id).events.last.seq,
+                        summary: summary })
+    end
+
+    private
+
+    # The last step/end's prompt_tokens is what the next request will roughly
+    # cost before compaction; over budget means compact now, while idle.
+    def overweight?(session_id)
+      last = @ctx[:sessions].fetch(session_id).events.reverse_each
+                            .find { |e| e.type == "step/end" }
+      tokens = last&.payload&.dig(:usage, :prompt_tokens)
+      !!(tokens && tokens >= @budget)
+    end
+  end
+
+  # ctx[:summarizer], the no-signup default: one model call through the
+  # :compactor role (a config row away on any adapter). Raises KeyError when
+  # the role is unconfigured — set the role or mount a provider that doesn't
+  # need one (terret-morph).
+  class RoleSummarizer < Hames::Service
+    service_key :summarizer
+    inject :llm
+    config_schema role: { type: [String, Symbol], default: :compactor,
+                          doc: "llm role a summary is produced under" }
+
+    PROMPT = <<~TEXT
+      Summarize the conversation so far for your own future context. Preserve
+      user goals and constraints, decisions made, tool results that still
+      matter, and open questions. Reply with one compact briefing only.
+    TEXT
+
+    def start(ctx)
+      @ctx = ctx
+    end
+
+    def reconfigure(_config); end # :role is read per call — already live
+
+    def summarize(history)
+      request = LLM::Request.new(model: nil, system: PROMPT, messages: history, tools: [])
+      @ctx[:llm].stream(@ctx, role: config[:role] || :compactor, request: request) { |_ev| }.text
+    end
+  end
+end

data/lib/terret/credentials.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+require "openssl"
+
+module Terret
+  # ctx[:credentials] — plan §6.9. The one place a provider's secret is
+  # resolved, and its security point: every value it resolves is fed to the
+  # session scrubber (Sessions#register_scrubber), so a resolved credential can
+  # never reach the durable log even if a tool echoes it back into a result.
+  # That is what makes this more than a lookup table — it closes the loop the
+  # config-pattern redactor (docs/exec.md §6) leaves open, catching a secret by
+  # its exact bytes rather than by a shape a deployment had to name in advance.
+  #
+  # Resolution order is ENV-first by convention (`<PROVIDER>_API_KEY`), then an
+  # optional encrypted file store. ENV ALWAYS wins; the file is consulted only
+  # when ENV is silent (unset or empty), and a file present with no master key
+  # REFUSES rather than falling back to anything unprotected.
+  #
+  # On-disk format (a deployment writes it; a `trt credentials set` CLI is
+  # future work, plan §14 — only the format is promised here): JSON at the
+  # configured `file:` path, mapping each provider name to
+  #
+  #   Base64.strict_encode64( iv(12 bytes) || auth_tag(16 bytes) || ciphertext )
+  #
+  # each entry AES-256-GCM under a 32-byte master key. The master key is ENV
+  # `TERRET_CREDENTIALS_KEY`, itself Base64 of exactly 32 bytes — generate one
+  # with `openssl rand -base64 32`. Both the file and the key are optional: with
+  # neither, ENV `<PROVIDER>_API_KEY` resolves on its own and the file store is
+  # inert, which is the shipped default.
+  #
+  # Deferred (plan §14): an OS-keychain backend, and the writer CLI above.
+  class Credentials < Hames::Service
+    service_key :credentials
+    inject :sessions
+    config_schema file: { type: String,
+                          doc: "path to an AES-256-GCM encrypted credential store, provider => " \
+                               "base64(iv+tag+ciphertext); the master key is ENV " \
+                               "TERRET_CREDENTIALS_KEY (base64 of 32 bytes) and the per-provider " \
+                               "ENV <PROVIDER>_API_KEY always wins — neither is config, and with " \
+                               "no file only ENV resolves" }
+
+    class Error < StandardError; end
+
+    IV_LEN  = 12  # AES-GCM standard nonce
+    TAG_LEN = 16  # AES-GCM authentication tag
+    KEY_LEN = 32  # AES-256
+
+    # Below this an exact-string scrub would match far too much: the empty
+    # string inserts the token between every character, and a two-character
+    # value paints ordinary prose. A real resolved credential dwarfs this
+    # floor, so a value under it is still resolved and returned — it just does
+    # not become an active scrub pattern (fail-safe: never corrupt the log to
+    # chase a value too short to be a secret worth catching by its bytes).
+    MIN_SCRUB_LENGTH = 8
+    REPLACEMENT = "[REDACTED]"
+
+    def start(ctx)
+      @secrets = []
+      @mutex = Mutex.new
+      # ONE scrubber over the growing set rather than a fresh registration per
+      # resolve: re-resolving a provider must not stack duplicate scrubbers, and
+      # a scrubber reaches every append whether it was registered early or late.
+      ctx[:sessions].register_scrubber(method(:scrub))
+    end
+
+    def reconfigure(_config); end # the file path is read per resolve
+
+    # The credential for a provider by name, or nil. ENV wins; then the file
+    # store when configured. A non-trivial resolved value is registered as an
+    # exact-string scrub pattern before it is returned, so anything that later
+    # echoes it into the log is caught.
+    def resolve(provider)
+      name = provider.to_s
+      env = ENV["#{env_name(name)}_API_KEY"]
+      value = (env unless env.nil? || env.empty?) || from_file(name)
+      remember(value) if value
+      value
+    end
+
+    private
+
+    # Exact-string, block-form gsub: never a Regexp a value's own metacharacters
+    # could turn into an over-match, and never gsub's STRING replacement (a `\0`
+    # inside a secret would paste the secret back in). Reads a snapshot under
+    # the lock so a concurrent resolve cannot mutate the set mid-fold.
+    def scrub(text)
+      @mutex.synchronize { @secrets.dup }.reduce(text) do |acc, secret|
+        acc.gsub(secret) { REPLACEMENT }
+      end
+    end
+
+    def remember(value)
+      return unless value.length >= MIN_SCRUB_LENGTH
+
+      @mutex.synchronize { @secrets << value unless @secrets.include?(value) }
+    end
+
+    # openrouter => OPENROUTER; a hyphen or dot in a provider name becomes an
+    # underscore so the env var is a legal shell identifier.
+    def env_name(name) = name.upcase.gsub(/[^A-Z0-9]/, "_")
+
+    # nil when no file is configured or it does not exist; RAISES when the file
+    # exists but no master key is set — never a plaintext or unprotected
+    # fallback. Read fresh each resolve, so a deployment can rewrite the store
+    # without a remount.
+    def from_file(name)
+      store = file_store or return nil
+      entry = store[name] or return nil
+
+      blob = begin
+        Base64.strict_decode64(entry.to_s)
+      rescue ArgumentError
+        raise Error, "a credential store entry is not valid Base64 " \
+                     "(a truncated or corrupted store); refusing to resolve"
+      end
+      decrypt(blob)
+    end
+
+    def file_store
+      path = config[:file]
+      return nil unless path && File.exist?(path)
+
+      unless master_key
+        raise Error, "credential store #{path.inspect} exists but TERRET_CREDENTIALS_KEY is not " \
+                     "set; refusing to resolve credentials without the master key"
+      end
+
+      parsed = JSON.parse(File.read(path))
+      raise Error, "credential store #{path.inspect} is not a JSON object" unless parsed.is_a?(Hash)
+
+      parsed
+    end
+
+    # nil only when the key is absent/empty; a present-but-malformed key RAISES
+    # rather than reading as absent, so a typo refuses instead of silently
+    # skipping to a fallback.
+    def master_key
+      raw = ENV["TERRET_CREDENTIALS_KEY"]
+      return nil if raw.nil? || raw.empty?
+
+      key = begin
+        Base64.strict_decode64(raw)
+      rescue ArgumentError
+        raise Error, "TERRET_CREDENTIALS_KEY is not valid Base64"
+      end
+      unless key.bytesize == KEY_LEN
+        raise Error, "TERRET_CREDENTIALS_KEY must be Base64 of exactly #{KEY_LEN} bytes (an AES-256 key)"
+      end
+
+      key
+    end
+
+    def decrypt(blob)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+      cipher.key = master_key
+      cipher.iv = blob.byteslice(0, IV_LEN)
+      cipher.auth_tag = blob.byteslice(IV_LEN, TAG_LEN)
+      plaintext = cipher.update(blob.byteslice(IV_LEN + TAG_LEN..) || "") + cipher.final
+      plaintext.force_encoding(Encoding::UTF_8)
+    rescue OpenSSL::Cipher::CipherError, ArgumentError, TypeError => e
+      # CipherError is the wrong-key/tampered case; ArgumentError and TypeError
+      # are what a TRUNCATED blob raises before decryption even begins — an iv or
+      # auth tag of the wrong length, or a nil slice past the end of the bytes.
+      # All three mean the entry cannot be decrypted, and all three fail closed
+      # through the friendly Error rather than a raw crypto backtrace.
+      raise Error, "a credential store entry failed to decrypt " \
+                   "(wrong master key, or a truncated or tampered store): #{e.message}"
+    end
+  end
+end