insika 0.0.1 → 0.1.0

data/lib/insika/channels/relay.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "openssl"
+require "uri"
+
+module Insika
+  module Channels
+    # The channel for an adopter who ALREADY owns a messaging integration
+    # (RFC-0011 §6). A WhatsApp BSP, a Zendesk, a legacy Rails app: they want the
+    # engine for the TURN, not for the platform. Two routes and an envelope —
+    #
+    #   consumer --POST /channels/relay/events--> engine   acked now, never the reply
+    #   consumer <--POST <deliver_url>---------- engine    the reply, when there is one
+    #
+    # — and everything platform-shaped stays theirs: the 24-hour window, template
+    # approval, media, read receipts, and how markdown becomes WhatsApp formatting
+    # (§6.3). That is the promise, not the limitation: an integration someone has
+    # already tuned for years does not have to move for them to adopt the engine.
+    # A relay that starts growing template logic has stopped being a relay.
+    #
+    # It is also the cheapest possible Shape B, which is why it is built first:
+    # both ends are ours, so there is no third-party signature scheme and no
+    # rendering to get wrong at the same time as the durability. What it DOES
+    # exercise — the outbox, the claim, bounded retry, inbound dedup — is what
+    # Slack and native WhatsApp inherit untouched.
+    #
+    # R1/R2 hold: this object translates and authenticates, and does nothing else.
+    # No Executor, no store, no RubyLLM; it may refuse a request, never grant a
+    # capability.
+    class Relay
+      DEFAULT_ID = "relay"
+      DEFAULT_TIMEOUT = 10
+
+      attr_reader :id
+
+      # The bundled relay as an operator configures it: three env vars, of which the
+      # token is the SWITCH — no token, no channel, so there is no way to end up with
+      # this route mounted and open. -> Relay | nil.
+      #
+      # Shared by every composition root on purpose: the DSL front door has to reach
+      # the same feature as `config.ru`, or the docs are true of only one of them.
+      def self.from_env(env = ENV, http: nil, allow_http: false, allow_private: false)
+        token = Insika::EnvSchema.read("INSIKA_RELAY_TOKEN", env)
+        return nil unless Insika::EnvSchema.present?(token)
+
+        new(inbound_token: token,
+            deliver_url: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_URL", env),
+            deliver_token: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_TOKEN", env),
+            http: http, allow_http: allow_http, allow_private: allow_private)
+      end
+
+      # inbound_token:  shared secret the consumer sends us (Bearer). Blank ->
+      #                 the channel answers :disabled to every request, fail-closed
+      #                 by construction rather than open by omission.
+      # deliver_url:    where the reply goes. Blank -> nothing is ever delivered
+      #                 (the channel still accepts inbound; the outbox records the
+      #                 reply and the delivery fails loudly instead of silently).
+      # deliver_token:  Bearer we send THEM. Optional: a consumer on a private
+      #                 network may authenticate us another way.
+      def initialize(inbound_token:, deliver_url:, deliver_token: nil, http: nil,
+                     id: DEFAULT_ID, allow_http: false, allow_private: false,
+                     timeout: DEFAULT_TIMEOUT)
+        @id = id.to_s
+        @inbound_token = inbound_token.to_s
+        @deliver_url = deliver_url.to_s
+        @deliver_token = deliver_token.to_s
+        @http = http || Insika::HttpClient.new
+        @allow_http = allow_http
+        @allow_private = allow_private
+        @timeout = timeout
+      end
+
+      # -> :ok | :unauthorized | :disabled. A SYMBOL and not a Rack triple (the
+      # RFC sketched one): a status code is the transport's vocabulary, and keeping
+      # it out of here is what lets this class be tested without Rack and read
+      # without knowing HTTP.
+      def authenticate(req)
+        return :disabled if @inbound_token.empty?
+
+        provided = req.get_header("HTTP_AUTHORIZATION").to_s[/\ABearer (.+)\z/, 1]
+        return :unauthorized if provided.nil?
+
+        secure_compare(@inbound_token, provided) ? :ok : :unauthorized
+      end
+
+      # Inbound envelope -> the fields the mount turns into a `:send_message`.
+      # STRING keys in, because the consumer's `vars` are arbitrary data keys.
+      #
+      #   { "agent": "support", "external_id": "5511999998888",
+      #     "event_id": "wamid.HBg…", "message": "queria saber do pedido",
+      #     "vars": { … } }
+      def parse(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        agent = string(body["agent"])
+        external_id = string(body["external_id"])
+        message = string(body["message"])
+
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+        raise Insika::ValidationError, "external_id is required" if external_id.empty?
+        raise Insika::ValidationError, "message is required" if message.strip.empty?
+
+        vars = body["vars"].is_a?(Hash) ? body["vars"] : {}
+        { agent: agent, external_id: external_id, message: message,
+          event_id: presence(body["event_id"]), vars: vars }
+      end
+
+      # RFC-0011 §4.3 — the engine namespaces the platform's conversation key, so a
+      # Slack channel id and a phone number can never collide, an operator can see
+      # where a conversation came from, and an id minted for one channel cannot be
+      # used to read another's session.
+      def session_id_for(external_id) = "#{@id}:#{external_id}"
+
+      # The reverse: what the consumer called this conversation. Reads off the
+      # session id so a delivery needs no extra state.
+      def external_id_from(session_id)
+        s = session_id.to_s
+        s.start_with?("#{@id}:") ? s.delete_prefix("#{@id}:") : nil
+      end
+
+      # Hands ONE reply to the consumer's callback. -> the HTTP status (the
+      # dispatcher decides what 2xx means); raises DeliveryError when the request
+      # could not be made at all.
+      #
+      # `X-Insika-Delivery` is the outbox id: a stable idempotency key, so a
+      # consumer that receives the same delivery twice (we retried after a timeout
+      # that actually landed) can drop the second one.
+      def deliver(payload, to:, delivery_id: nil)
+        raise Insika::DeliveryError, "relay deliver_url is not configured" if @deliver_url.empty?
+
+        if (reason = egress_violation)
+          raise Insika::DeliveryError, "egress blocked for deliver_url: #{reason}"
+        end
+
+        response = @http.request(method: :post, url: @deliver_url, timeout: @timeout,
+                                 headers: headers(delivery_id),
+                                 body: JSON.generate(payload.merge("external_id" => to.to_s)))
+        response[:status].to_i
+      rescue Insika::DeliveryError
+        raise
+      rescue StandardError => e
+        raise Insika::DeliveryError, "#{e.class}: #{e.message}"
+      end
+
+      private
+
+      # Resolved on EVERY call, not once at boot: a hostname that answered a public
+      # address yesterday can answer 169.254.169.254 today, and this POST carries
+      # the customer's conversation.
+      def egress_violation
+        Insika::EgressGuard.violation(@deliver_url, allow_http: @allow_http,
+                                                    allow_private: @allow_private,
+                                                    host_allowlist: [URI.parse(@deliver_url).host].compact)
+      rescue URI::InvalidURIError
+        "invalid URL"
+      end
+
+      def headers(delivery_id)
+        h = { "content-type" => "application/json" }
+        h["authorization"] = "Bearer #{@deliver_token}" unless @deliver_token.empty?
+        h["x-insika-delivery"] = delivery_id.to_s if delivery_id
+        h
+      end
+
+      # Constant time, and length-safe: comparing the digests means an attacker
+      # learns nothing from how long the check took, not even the token's length.
+      # OpenSSL rather than Rack::Utils so the engine's lib/ keeps no web framework
+      # in its load path.
+      def secure_compare(a, b)
+        OpenSSL.fixed_length_secure_compare(Digest::SHA256.digest(a), Digest::SHA256.digest(b))
+      end
+
+      def string(value) = value.to_s
+      def presence(value) = Insika::Coercion.presence(value)
+    end
+  end
+end

data/lib/insika/channels/web/widget.js

@@ -0,0 +1,283 @@
+// Insika web widget (RFC-0011 §5.2).
+//
+// One <script> tag, no framework, no build step, no dependency:
+//
+//   <script src="https://agents.example.com/channels/web/asset/widget.js"
+//           data-agent="support" data-title="Ask us anything" defer></script>
+//
+// Everything it needs it reads off its own tag: the agent, the chrome text, and
+// the engine's base URL (derived from this file's own src, so an adopter never
+// configures a host twice). Theming is a block of CSS custom properties — set
+// them on :root and they win, because they are declared on the widget root with
+// var(..., fallback).
+//
+// The one design decision worth stating: a message POST is NEVER retried. It is
+// the request that runs a turn, so re-sending it costs a second LLM call and can
+// put a second answer in front of the customer. A dropped stream shows what
+// arrived plus a failure note, and the person decides whether to ask again. The
+// backoff below is for minting a session — the only call here that is safe to
+// repeat.
+(function () {
+  "use strict";
+
+  var script = document.currentScript;
+  if (!script) return;
+
+  var base = new URL(script.src, window.location.href).href.replace(/\/channels\/[^/]+\/asset\/[^/]*$/, "");
+  var channel = (script.src.match(/\/channels\/([^/]+)\/asset\//) || [])[1] || "web";
+  var agent = script.dataset.agent || "";
+  var title = script.dataset.title || "Chat";
+  var placeholder = script.dataset.placeholder || "Type a message…";
+  var greeting = script.dataset.greeting || "";
+  var storageKey = "insika:" + channel + ":" + agent + ":session";
+
+  if (!agent) {
+    console.error("[insika] the widget needs data-agent on its <script> tag");
+    return;
+  }
+
+  // --- chrome ---------------------------------------------------------
+
+  var CSS = [
+    ".insika-w{position:fixed;right:var(--insika-offset,20px);bottom:var(--insika-offset,20px);z-index:2147483000;",
+    "font-family:var(--insika-font,system-ui,-apple-system,Segoe UI,Roboto,sans-serif);font-size:15px;line-height:1.5}",
+    ".insika-b{width:56px;height:56px;border-radius:50%;border:0;cursor:pointer;display:block;margin-left:auto;",
+    "background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff);font-size:24px;",
+    "box-shadow:0 6px 24px rgba(0,0,0,.22)}",
+    ".insika-p{display:none;flex-direction:column;width:min(380px,calc(100vw - 40px));height:min(560px,calc(100vh - 120px));",
+    "margin-bottom:12px;border-radius:14px;overflow:hidden;background:var(--insika-bg,#fff);color:var(--insika-fg,#111827);",
+    "border:1px solid var(--insika-border,rgba(0,0,0,.12));box-shadow:0 12px 48px rgba(0,0,0,.24)}",
+    ".insika-w.open .insika-p{display:flex}",
+    ".insika-h{padding:12px 14px;font-weight:600;background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff);",
+    "display:flex;align-items:center;justify-content:space-between}",
+    ".insika-x{background:none;border:0;color:inherit;font-size:20px;cursor:pointer;line-height:1;padding:0 2px}",
+    ".insika-log{flex:1;overflow-y:auto;padding:14px;display:flex;flex-direction:column;gap:10px}",
+    ".insika-m{max-width:85%;padding:9px 12px;border-radius:12px;white-space:pre-wrap;overflow-wrap:anywhere}",
+    ".insika-m.user{align-self:flex-end;background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff)}",
+    ".insika-m.agent{align-self:flex-start;background:var(--insika-muted,#f3f4f6);color:var(--insika-fg,#111827)}",
+    ".insika-m.note{align-self:center;font-size:13px;opacity:.7;background:none;padding:2px}",
+    ".insika-f{display:flex;gap:8px;padding:10px;border-top:1px solid var(--insika-border,rgba(0,0,0,.12))}",
+    ".insika-f input{flex:1;min-width:0;padding:9px 11px;border-radius:9px;font:inherit;color:inherit;background:transparent;",
+    "border:1px solid var(--insika-border,rgba(0,0,0,.18))}",
+    ".insika-f button{padding:9px 14px;border:0;border-radius:9px;cursor:pointer;font:inherit;",
+    "background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff)}",
+    ".insika-f button[disabled]{opacity:.5;cursor:default}"
+  ].join("");
+
+  var style = document.createElement("style");
+  style.textContent = CSS;
+  document.head.appendChild(style);
+
+  var root = el("div", "insika-w");
+  var panel = el("div", "insika-p");
+  var header = el("div", "insika-h");
+  var log = el("div", "insika-log");
+  var form = document.createElement("form");
+  var input = document.createElement("input");
+  var send = document.createElement("button");
+  var bubble = el("button", "insika-b");
+
+  header.appendChild(text("span", title));
+  var close = el("button", "insika-x");
+  close.type = "button";
+  close.textContent = "×";
+  close.setAttribute("aria-label", "Close");
+  header.appendChild(close);
+
+  form.className = "insika-f";
+  input.type = "text";
+  input.placeholder = placeholder;
+  input.setAttribute("aria-label", placeholder);
+  send.type = "submit";
+  send.textContent = "Send";
+  form.appendChild(input);
+  form.appendChild(send);
+
+  panel.appendChild(header);
+  panel.appendChild(log);
+  panel.appendChild(form);
+
+  bubble.type = "button";
+  bubble.textContent = "💬";
+  bubble.setAttribute("aria-label", title);
+
+  root.appendChild(panel);
+  root.appendChild(bubble);
+  document.body.appendChild(root);
+
+  if (greeting) say("agent", greeting);
+
+  bubble.addEventListener("click", toggle);
+  close.addEventListener("click", toggle);
+  form.addEventListener("submit", function (e) {
+    e.preventDefault();
+    var value = input.value.trim();
+    if (!value || busy) return;
+    input.value = "";
+    ask(value);
+  });
+
+  function toggle() {
+    root.classList.toggle("open");
+    if (root.classList.contains("open")) input.focus();
+  }
+
+  // --- the turn -------------------------------------------------------
+
+  var busy = false;
+
+  function ask(message) {
+    busy = true;
+    send.disabled = true;
+    say("user", message);
+
+    var bubbleEl = null;
+    var note = null;
+
+    session()
+      .then(function (id) {
+        return fetch(base + "/channels/" + channel + "/messages", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ agent: agent, session_id: id, message: message })
+        });
+      })
+      .then(function (res) {
+        // An unknown session id (the store was wiped, the id expired) is the one
+        // recoverable failure: drop ours and let the next message mint a new one.
+        if (res.status === 404) {
+          forget();
+          throw new Error("session expired — please send that again");
+        }
+        if (!res.ok || !res.body) throw new Error("the assistant is unavailable right now");
+        return read(res.body.getReader(), function (event, data) {
+          if (event === "delta" && data.delta) {
+            if (note) { note.remove(); note = null; }
+            if (!bubbleEl) bubbleEl = say("agent", "");
+            bubbleEl.textContent += data.delta;
+            log.scrollTop = log.scrollHeight;
+          } else if (event === "working" && !bubbleEl && !note) {
+            note = say("note", "working…");
+          } else if (event === "error") {
+            if (note) { note.remove(); note = null; }
+            throw new Error(data.message || "something went wrong");
+          }
+        });
+      })
+      .catch(function (err) {
+        if (note) note.remove();
+        say("note", err.message || "something went wrong");
+      })
+      .finally(function () {
+        busy = false;
+        send.disabled = false;
+        input.focus();
+      });
+  }
+
+  // The engine issues the session id; we only ever store the one it gave us
+  // (RFC-0011 §4.3 — a client that proposes its own id on a public endpoint is
+  // one enumeration away from reading someone else's conversation).
+  function session() {
+    var saved = remembered;
+    if (saved) return Promise.resolve(saved);
+
+    return mint(0).then(function (id) {
+      remember(id);
+      return id;
+    });
+  }
+
+  // localStorage THROWS (not returns null) in a sandboxed iframe, in Safari's
+  // private mode and wherever site data is blocked. Reading it unguarded would
+  // throw out of `ask` before the .catch is attached, leaving the send button
+  // disabled forever. So the conversation degrades to in-memory instead: it lives
+  // for the page, which is worse than remembering and much better than frozen.
+  var remembered = read_storage();
+
+  function read_storage() {
+    try { return localStorage.getItem(storageKey); } catch (e) { return null; }
+  }
+
+  function remember(id) {
+    remembered = id;
+    try { localStorage.setItem(storageKey, id); } catch (e) { /* in-memory only */ }
+  }
+
+  function forget() {
+    remembered = null;
+    try { localStorage.removeItem(storageKey); } catch (e) { /* in-memory only */ }
+  }
+
+  // 1s → 30s backoff, one attempt in flight, the same discipline the Studio's
+  // live transcript uses. Safe to repeat because minting has no side effect the
+  // customer can see: the worst case is an unused empty session.
+  function mint(attempt) {
+    return fetch(base + "/channels/" + channel + "/sessions", { method: "POST" })
+      .then(function (res) {
+        if (!res.ok) throw new Error("HTTP " + res.status);
+        return res.json();
+      })
+      .then(function (body) {
+        if (!body.session_id) throw new Error("no session id");
+        return body.session_id;
+      })
+      .catch(function (err) {
+        if (attempt >= 4) throw new Error("cannot reach the assistant right now");
+        var wait = Math.min(30000, 1000 * Math.pow(2, attempt));
+        return delay(wait).then(function () { return mint(attempt + 1); });
+      });
+  }
+
+  // Minimal SSE reader over fetch — EventSource cannot POST, and the turn is a
+  // POST. Frames are `event: <name>\ndata: <json>\n\n`; anything else is skipped,
+  // so a frame added later cannot break an old widget.
+  function read(reader, onEvent) {
+    var decoder = new TextDecoder();
+    var buffer = "";
+
+    return reader.read().then(function step(chunk) {
+      if (chunk.done) return;
+      buffer += decoder.decode(chunk.value, { stream: true });
+
+      var parts = buffer.split("\n\n");
+      buffer = parts.pop();
+      parts.forEach(function (frame) {
+        var name = (frame.match(/^event: (.+)$/m) || [])[1];
+        var raw = (frame.match(/^data: (.*)$/m) || [])[1];
+        if (!name) return;
+        var data = {};
+        try { data = raw ? JSON.parse(raw) : {}; } catch (e) { return; }
+        onEvent(name, data);
+      });
+
+      return reader.read().then(step);
+    });
+  }
+
+  // --- helpers --------------------------------------------------------
+
+  function say(kind, content) {
+    var node = el("div", "insika-m " + kind);
+    node.textContent = content;
+    log.appendChild(node);
+    log.scrollTop = log.scrollHeight;
+    return node;
+  }
+
+  function el(tag, className) {
+    var node = document.createElement(tag);
+    node.className = className;
+    return node;
+  }
+
+  function text(tag, content) {
+    var node = document.createElement(tag);
+    node.textContent = content;
+    return node;
+  }
+
+  function delay(ms) {
+    return new Promise(function (resolve) { setTimeout(resolve, ms); });
+  }
+})();

data/lib/insika/channels/web.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+
+module Insika
+  module Channels
+    # The web widget (RFC-0011 §5) — the FIRST Shape A channel, and the adoption
+    # claim behind the whole RFC: an adopter pastes one tag into their site and has
+    # a working agent, with no backend of their own and no build step.
+    #
+    #   <script src="https://agents.example.com/channels/web/asset/widget.js"
+    #           data-agent="support" data-title="Ask us anything" defer></script>
+    #
+    # Shape A means the reply comes back on the request's own stream, so there is
+    # no outbox, no claim and no `deliver` here — the three routes and a static
+    # asset are the entire surface:
+    #
+    #   POST /channels/web/sessions      mint an opaque session id (the engine's, §4.3)
+    #   POST /channels/web/messages      the turn, answered as SSE on this connection
+    #   GET  /channels/web/asset/widget.js
+    #
+    # What makes this channel different from the relay is that it is PUBLIC: the
+    # caller is an anonymous browser, so there is no shared secret to check and the
+    # money faucet is real. Three things stand in for the missing credential, and
+    # all three are refusals, never grants (R2):
+    #
+    #   · an AGENT allowlist — a visitor addresses the agents the operator published
+    #     to the widget, not every agent in the deployment;
+    #   · an ORIGIN allowlist — exact match, no wildcards, and no "allow all" value;
+    #   · a mandatory chat RATE LIMIT (§5.4) — the channel answers `:disabled`
+    #     until one is configured, because a public endpoint with an LLM behind it
+    #     and no ceiling is an unmetered bill waiting to happen.
+    #
+    # R1/R2 hold: this object translates and refuses, and does nothing else. No
+    # Executor, no store, no RubyLLM — the rate-limit probe is injected as a plain
+    # callable so the channel never learns what a profile or a settings store is.
+    class Web
+      DEFAULT_ID = "web"
+
+      # The static files this channel serves, by request name. A closed map, not a
+      # directory listing: `asset/:f` takes a name from the URL, and anything that
+      # resolves a path from user input is a traversal waiting to be found.
+      ASSETS = {
+        "widget.js" => { file: "web/widget.js", content_type: "application/javascript; charset=utf-8" }
+      }.freeze
+
+      # An unversioned URL cannot be cached for a year — the next release would
+      # never reach a browser that already has it. Short max-age + an ETag instead:
+      # the common case is a 304 with no body, and an upgrade lands within minutes.
+      # (A deliberate narrowing of §5.2's "long-cache versioned URL": the install
+      # snippet in the RFC has no version in it, so there is nothing to bust.)
+      ASSET_CACHE_CONTROL = "public, max-age=300"
+
+      attr_reader :id
+
+      # The bundled widget as an operator configures it. BOTH allowlists are the
+      # switch: a widget with no origins can be embedded nowhere, and one with no
+      # agents can address nothing, so either one missing means the operator has not
+      # actually asked for this channel. -> Web | nil.
+      def self.from_env(env = ENV, id: DEFAULT_ID, chat_rate_limit: nil)
+        origins = csv(Insika::EnvSchema.read("INSIKA_WIDGET_ORIGINS", env))
+        agents  = csv(Insika::EnvSchema.read("INSIKA_WIDGET_AGENTS", env))
+        return nil if origins.empty? || agents.empty?
+
+        new(origins: origins, agents: agents, id: id, chat_rate_limit: chat_rate_limit)
+      end
+
+      # The probe §5.4's gate needs, asked exactly the way `EdgeLimiter` asks it at
+      # turn time: the per-agent override first, the platform default second. Built
+      # here so both composition roots wire the gate identically, and returned as a
+      # lambda so the channel itself stays store-free.
+      #
+      # Resolved on every check rather than at boot: an operator who removes the
+      # limit tomorrow closes the widget, instead of leaving it open because it was
+      # configured correctly once.
+      def self.limit_resolver(profiles:, settings_store: nil)
+        lambda do |agent_id|
+          limits = profiles&.fetch(agent_id.to_s)&.limits || {}
+          next limits[:chat_rate_limit] if limits.key?(:chat_rate_limit)
+
+          ((settings_store&.get || {})["edge"] || {})["chat_rate_limit"]
+        end
+      end
+
+      def self.csv(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+      # origins:         exact-match origin allowlist (`https://shop.example`). No
+      #                  wildcard, no "*" — CORS is a browser courtesy and a value
+      #                  that means "anyone" would only make it look like a control.
+      # agents:          agent ids a visitor may address.
+      # chat_rate_limit: callable(agent_id) -> the effective limit, or nil. Absent ⇒
+      #                  the channel is `:disabled`, which is the fail-closed
+      #                  reading of "no ceiling configured".
+      def initialize(origins:, agents:, id: DEFAULT_ID, chat_rate_limit: nil)
+        @id = id.to_s
+        @origins = Array(origins).map(&:to_s)
+        @agents = Array(agents).map(&:to_s)
+        @chat_rate_limit = chat_rate_limit
+        @assets = {}
+      end
+
+      # -> :ok | :unauthorized | :disabled. Same verdict vocabulary as every other
+      # channel (no Rack triple in `lib/`), and the same fail-closed default.
+      #
+      # A request with NO `Origin` is not a browser, so there is nothing for CORS to
+      # protect and refusing it would be theatre — curl can always set any origin it
+      # likes. The rate limit is what actually defends this route, which is why it
+      # is checked here and not left to the operator's memory.
+      def authenticate(req)
+        return :disabled if @agents.empty?
+        return :disabled unless rate_limited?
+
+        origin = req.get_header("HTTP_ORIGIN").to_s
+        return :ok if origin.empty?
+
+        allowed_origin?(origin) ? :ok : :unauthorized
+      end
+
+      # Is a chat rate limit configured for EVERY agent the widget publishes? All of
+      # them and not just the one being addressed: the check runs before the body is
+      # parsed, and "the widget is open for agent A but closed for agent B" is a
+      # posture nobody can hold in their head.
+      def rate_limited?
+        return false if @chat_rate_limit.nil?
+
+        !@agents.empty? && @agents.all? { |agent| @chat_rate_limit.call(agent).to_i.positive? }
+      end
+
+      # POST /channels/web/messages — STRING keys in, because this body comes off
+      # the public internet and nothing in it should become a symbol.
+      #
+      #   { "agent": "support", "session_id": "web:8f3c…", "message": "oi" }
+      #
+      # The agent allowlist is checked HERE, which is a refusal and not a grant: the
+      # profile still decides what that agent may do.
+      def parse(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        agent = body["agent"].to_s.strip
+        session_id = body["session_id"].to_s.strip
+        message = body["message"].to_s
+
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+        raise Insika::ValidationError, "agent '#{agent}' is not published to the widget" unless @agents.include?(agent)
+        raise Insika::ValidationError, "session_id is required" if session_id.empty?
+        raise Insika::ValidationError, "message is required" if message.strip.empty?
+
+        { agent: agent, session_id: session_id, message: message }
+      end
+
+      # §4.3's hard rule for a public channel: the ENGINE issues the id and the
+      # client never proposes one. A visitor-supplied session id on an anonymous
+      # endpoint is session hijacking by enumeration, so there is no create-on-write
+      # path — `POST /messages` with an unknown id is a 404, not a new conversation.
+      def mint_session_id = "#{@id}:#{SecureRandom.hex(16)}"
+
+      # Turn Event -> SSE frame | nil. Four frames, which is the whole widget
+      # protocol: what to type, what to say while a tool runs, and how it ended.
+      #
+      # `:intermediate` and `:thinking` are deliberately absent. `:content` is the
+      # ANSWER (P19) — the model's narration on the way there is internal, and a
+      # widget that rendered it would show the customer the engine thinking out loud.
+      def frame_for(event)
+        case event.type
+        when :content        then sse("delta", { delta: event.data[:delta].to_s })
+        when :tool_call      then sse("working", { name: event.data[:name].to_s })
+        when :task_completed then sse("done", {})
+        when :task_failed    then sse("error", { message: event.data[:message].to_s })
+        when :task_cancelled then sse("error", { message: "task cancelled" })
+        when :error          then sse("error", { message: event.data[:message].to_s })
+        end
+      end
+
+      # GET /channels/web/asset/:f -> { content_type:, body:, etag: } | nil.
+      # Read once and memoized: the file ships with the gem and cannot change under
+      # a running process.
+      def asset(name)
+        entry = ASSETS[name.to_s]
+        return nil if entry.nil?
+
+        @assets[name.to_s] ||= begin
+          body = File.read(File.expand_path(entry[:file], __dir__))
+          { content_type: entry[:content_type], body: body,
+            etag: %("#{Digest::SHA256.hexdigest(body)[0, 16]}"),
+            cache_control: ASSET_CACHE_CONTROL }
+        end
+      end
+
+      # -> the CORS headers for this request's origin. An origin that is not on the
+      # list simply gets none, and the browser refuses the response itself — the
+      # engine does not have to pretend that is an authorization decision.
+      def cors_headers(origin)
+        o = origin.to_s
+        return { "vary" => "origin" } unless allowed_origin?(o)
+
+        { "access-control-allow-origin" => o,
+          "vary" => "origin",
+          "access-control-allow-headers" => "content-type",
+          "access-control-allow-methods" => "POST, OPTIONS",
+          "access-control-max-age" => "600" }
+      end
+
+      private
+
+      def allowed_origin?(origin) = !origin.empty? && @origins.include?(origin)
+
+      def sse(name, data) = "event: #{name}\ndata: #{JSON.generate(data)}\n\n"
+    end
+  end
+end