@axis-network/butter-col 0.0.0-stage → 0.1.0

package/server/lua/butter/dns.lua

@@ -0,0 +1,67 @@
+-- DNS resolution with a shared cache. The proxy connects to the address it
+-- resolved and checked here, so DNS rebinding cannot slip past the guard.
+
+local resolver = require "resty.dns.resolver"
+local ip = require "butter.ip"
+
+local M = {}
+
+local function decode(cached)
+  local out = {}
+  for text in cached:gmatch("[^,]+") do
+    local bytes, version = ip.parse(text)
+    if bytes then out[#out + 1] = { bytes = bytes, version = version } end
+  end
+  return out
+end
+
+local function query(r, host, qtype)
+  local answers, err = r:query(host, { qtype = qtype })
+  if not answers then return nil, err end
+  if answers.errcode then return nil, answers.errstr or ("DNS error " .. answers.errcode) end
+  local addrs, ttl = {}, nil
+  for _, answer in ipairs(answers) do
+    if answer.type == qtype and answer.address then
+      addrs[#addrs + 1] = answer.address
+      ttl = ttl and math.min(ttl, answer.ttl or ttl) or answer.ttl
+    end
+  end
+  return addrs, nil, ttl
+end
+
+--- Resolve `host` to a list of { bytes, version }.
+-- @return table|nil, string|nil
+function M.resolve(host, cfg)
+  local cache = ngx.shared.butter_dns
+  local cached = cache:get(host)
+  if cached then
+    if cached:sub(1, 1) == "!" then return nil, cached:sub(2) end
+    return decode(cached)
+  end
+
+  local r, err = resolver:new({ nameservers = cfg.nameservers, retrans = cfg.retrans, timeout = cfg.timeout })
+  if not r then return nil, "cannot create resolver: " .. tostring(err) end
+
+  local addrs, qerr, ttl = query(r, host, r.TYPE_A)
+  if (not addrs or #addrs == 0) and cfg.ipv6 then
+    local addrs6, qerr6, ttl6 = query(r, host, r.TYPE_AAAA)
+    if addrs6 and #addrs6 > 0 then
+      addrs, ttl = addrs6, ttl6
+    else
+      qerr = qerr or qerr6
+    end
+  end
+
+  if not addrs or #addrs == 0 then
+    local message = qerr or "no addresses found"
+    cache:set(host, "!" .. message, cfg.negative_ttl)
+    return nil, message
+  end
+
+  ttl = math.max(cfg.min_ttl, math.min(cfg.max_ttl, ttl or cfg.min_ttl))
+  local text = table.concat(addrs, ",")
+  cache:set(host, text, ttl)
+  return decode(text)
+end
+
+return M

package/server/lua/butter/guard.lua

@@ -0,0 +1,78 @@
+-- Decides whether a target may be proxied and which address to connect to.
+
+local config = require "butter.config"
+local dns = require "butter.dns"
+local ip = require "butter.ip"
+
+local M = {}
+
+-- Ports browsers refuse to fetch (https://fetch.spec.whatwg.org/#bad-port).
+local BAD_PORTS = {}
+for _, port in ipairs({
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
+  103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465,
+  512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993,
+  995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668,
+  6669, 6679, 6697, 10080,
+}) do
+  BAD_PORTS[port] = true
+end
+
+--- Does `host` equal `pattern` or sit under it?
+local function host_matches(host, pattern)
+  pattern = pattern:lower():gsub("^%*?%.", "")
+  return host == pattern or (#host > #pattern and host:sub(-#pattern - 1) == "." .. pattern)
+end
+
+local function matches_any(host, list)
+  for _, pattern in ipairs(list or {}) do
+    if host_matches(host, pattern) then return true end
+  end
+  return false
+end
+
+--- Check a parsed target (butter.url) and pick the upstream address.
+-- @return table|nil, string|nil, string|nil  { addr = "ip:port", ip = "ip" } or nil, code, message
+function M.check(target)
+  local cfg = config.get()
+  local g = cfg.guard
+
+  if BAD_PORTS[target.port] and not g.allow_bad_ports then
+    return nil, "BLOCKED_PORT", "Port " .. target.port .. " is not allowed."
+  end
+  if matches_any(target.host, g.blocked_hosts) then
+    return nil, "BLOCKED_HOST", target.host .. " is blocked on this server."
+  end
+  if g.allowed_hosts and not matches_any(target.host, g.allowed_hosts) then
+    return nil, "BLOCKED_HOST", target.host .. " is not on this server's allow list."
+  end
+
+  local addrs
+  local literal, version = ip.parse(target.host)
+  if literal then
+    addrs = { { bytes = literal, version = version } }
+  elseif target.ipv6 then
+    return nil, "INVALID_URL", "Invalid IPv6 address."
+  else
+    local err
+    addrs, err = dns.resolve(target.host, cfg.dns)
+    if not addrs then
+      return nil, "DNS_FAILURE", "Could not resolve " .. target.host .. " (" .. tostring(err) .. ")."
+    end
+  end
+
+  if not g.allow_private then
+    for _, a in ipairs(addrs) do
+      if ip.is_reserved(a.bytes, a.version) then
+        return nil, "BLOCKED_ADDRESS", target.host .. " points to a private or reserved address."
+      end
+    end
+  end
+
+  local chosen = addrs[1]
+  local text = ip.to_string(chosen.bytes, chosen.version)
+  local host = chosen.version == 6 and ("[" .. text .. "]") or text
+  return { addr = host .. ":" .. target.port, ip = text }
+end
+
+return M

package/server/lua/butter/headers.lua

@@ -0,0 +1,83 @@
+-- Header rules for the transport. Pure Lua, no ngx dependency.
+
+local M = {}
+
+local function set(list)
+  local s = {}
+  for _, v in ipairs(list) do s[v] = true end
+  return s
+end
+
+-- Headers from the browser's own request to /butter/fetch that are forwarded
+-- upstream as-is (everything else is replaced by X-Butter-Headers).
+M.KEEP_OUTER = set({ "user-agent", "accept-language", "accept-encoding", "content-length", "transfer-encoding" })
+
+-- Never accepted from X-Butter-Headers.
+M.REQUEST_FORBIDDEN = set({
+  "host", "connection", "keep-alive", "proxy-connection", "proxy-authorization", "te", "trailer",
+  "transfer-encoding", "upgrade", "content-length", "cookie", "cookie2", "expect",
+  "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto", "x-real-ip", "forwarded", "via",
+  "user-agent", "accept-encoding",
+})
+
+-- Upstream response headers not reported in X-Butter-Headers.
+M.RESPONSE_SKIP = set({ "connection", "keep-alive", "transfer-encoding", "proxy-connection", "trailer", "upgrade" })
+
+-- Upstream response headers kept on the outer response so the browser
+-- decodes the body before the service worker sees it.
+M.OUTER_KEEP = set({ "content-encoding", "content-length" })
+
+M.MAX_HEADERS = 100
+M.MAX_VALUE = 16384
+
+function M.valid_name(name)
+  return type(name) == "string" and #name <= 256 and name:match("^[!#$%%&'*+%-%.%^_`|~%w]+$") ~= nil
+end
+
+function M.valid_value(value)
+  return type(value) == "string" and #value <= M.MAX_VALUE
+    and not value:find("[\r\n]") and not value:find("\0", 1, true)
+end
+
+--- Validate the decoded X-Butter-Headers object.
+-- @return table|nil, string|nil  list of { name, value }
+function M.sanitize_request(decoded)
+  if type(decoded) ~= "table" then return nil, "headers must be a JSON object" end
+  local out, count = {}, 0
+  for name, value in pairs(decoded) do
+    if not M.valid_name(name) then return nil, "invalid header name" end
+    if not M.valid_value(value) then return nil, "invalid value for header " .. name end
+    local lower = name:lower()
+    if not M.REQUEST_FORBIDDEN[lower] and lower:sub(1, 9) ~= "x-butter-" then
+      count = count + 1
+      if count > M.MAX_HEADERS then return nil, "too many headers" end
+      out[#out + 1] = { name, value }
+    end
+  end
+  table.sort(out, function(a, b) return a[1] < b[1] end)
+  return out
+end
+
+M.REASONS = {
+  [100] = "Continue", [101] = "Switching Protocols",
+  [200] = "OK", [201] = "Created", [202] = "Accepted", [203] = "Non-Authoritative Information",
+  [204] = "No Content", [205] = "Reset Content", [206] = "Partial Content",
+  [300] = "Multiple Choices", [301] = "Moved Permanently", [302] = "Found", [303] = "See Other",
+  [304] = "Not Modified", [307] = "Temporary Redirect", [308] = "Permanent Redirect",
+  [400] = "Bad Request", [401] = "Unauthorized", [402] = "Payment Required", [403] = "Forbidden",
+  [404] = "Not Found", [405] = "Method Not Allowed", [406] = "Not Acceptable", [407] = "Proxy Authentication Required",
+  [408] = "Request Timeout", [409] = "Conflict", [410] = "Gone", [411] = "Length Required",
+  [412] = "Precondition Failed", [413] = "Content Too Large", [414] = "URI Too Long",
+  [415] = "Unsupported Media Type", [416] = "Range Not Satisfiable", [417] = "Expectation Failed",
+  [418] = "I'm a teapot", [421] = "Misdirected Request", [422] = "Unprocessable Content", [425] = "Too Early",
+  [426] = "Upgrade Required", [428] = "Precondition Required", [429] = "Too Many Requests",
+  [431] = "Request Header Fields Too Large", [451] = "Unavailable For Legal Reasons",
+  [500] = "Internal Server Error", [501] = "Not Implemented", [502] = "Bad Gateway",
+  [503] = "Service Unavailable", [504] = "Gateway Timeout", [505] = "HTTP Version Not Supported",
+}
+
+function M.reason(status)
+  return M.REASONS[status] or ""
+end
+
+return M

package/server/lua/butter/init.lua

@@ -0,0 +1,18 @@
+-- butter-col server entry point (loaded by init_by_lua in nginx.conf).
+
+local M = {}
+
+--- @param config_path string|nil  user configuration; defaults to <prefix>/config.lua
+function M.init(config_path)
+  local config = require "butter.config"
+  local cfg = config.load(config_path or (ngx.config.prefix() .. "config.lua"))
+  -- Load everything now so workers share the compiled code (and so syntax
+  -- errors stop nginx at startup instead of at the first request).
+  require "butter.transport"
+  local names = {}
+  for i, entry in ipairs(cfg.transports) do names[i] = entry.name end
+  ngx.log(ngx.NOTICE, "butter-col ", config.VERSION, " ready (prefix ", cfg.prefix, ", codec ", cfg.codec,
+    ", transports ", table.concat(names, ","), ", default ", cfg.default_transport, ")")
+end
+
+return M

package/server/lua/butter/ip.lua

@@ -0,0 +1,165 @@
+-- IPv4 / IPv6 parsing and reserved-range checks for SSRF protection.
+-- Pure Lua (5.1 / LuaJIT / 5.3) without bit operators: addresses are byte arrays.
+
+local M = {}
+
+--- Parse dotted-quad IPv4. Rejects octal-looking parts like "010".
+-- @return table|nil  4 bytes
+function M.parse_v4(s)
+  local parts = { s:match("^(%d+)%.(%d+)%.(%d+)%.(%d+)$") }
+  if #parts ~= 4 then return nil end
+  local bytes = {}
+  for i = 1, 4 do
+    local p = parts[i]
+    if #p > 3 or (#p > 1 and p:sub(1, 1) == "0") then return nil end
+    local n = tonumber(p)
+    if n > 255 then return nil end
+    bytes[i] = n
+  end
+  return bytes
+end
+
+local function parse_groups(s)
+  local groups = {}
+  if s == "" then return groups end
+  for group in (s .. ":"):gmatch("([^:]*):") do
+    if not group:match("^%x%x?%x?%x?$") then return nil end
+    groups[#groups + 1] = tonumber(group, 16)
+  end
+  return groups
+end
+
+--- Parse IPv6 (with optional embedded IPv4 tail). Zone ids are rejected.
+-- @return table|nil  16 bytes
+function M.parse_v6(s)
+  if s:find("%", 1, true) then return nil end
+  local v4_tail
+  local last_colon = s:match("^.*():")
+  if last_colon and s:find(".", last_colon, true) then
+    v4_tail = M.parse_v4(s:sub(last_colon + 1))
+    if not v4_tail then return nil end
+    s = s:sub(1, last_colon)
+    if s:sub(-2) ~= "::" then s = s:sub(1, -2) end
+  end
+
+  local head, tail = s:match("^(.-)::(.*)$")
+  local groups
+  local extra = v4_tail and 2 or 0
+  if head then
+    if tail:find("::", 1, true) then return nil end
+    local h, t = parse_groups(head), parse_groups(tail)
+    if not h or not t then return nil end
+    local missing = 8 - extra - #h - #t
+    if missing < 1 then return nil end
+    groups = h
+    for _ = 1, missing do groups[#groups + 1] = 0 end
+    for _, g in ipairs(t) do groups[#groups + 1] = g end
+  else
+    groups = parse_groups(s)
+    if not groups or #groups ~= 8 - extra then return nil end
+  end
+
+  local bytes = {}
+  for _, g in ipairs(groups) do
+    bytes[#bytes + 1] = math.floor(g / 256)
+    bytes[#bytes + 1] = g % 256
+  end
+  if v4_tail then
+    for i = 1, 4 do bytes[#bytes + 1] = v4_tail[i] end
+  end
+  return bytes
+end
+
+--- @return table|nil, number|nil  bytes and version (4 or 6)
+function M.parse(s)
+  if type(s) ~= "string" then return nil end
+  local v4 = M.parse_v4(s)
+  if v4 then return v4, 4 end
+  if s:find(":", 1, true) then
+    local v6 = M.parse_v6(s)
+    if v6 then return v6, 6 end
+  end
+  return nil
+end
+
+--- Does `bytes` fall inside network/bits?
+function M.in_cidr(bytes, network, bits)
+  for i = 1, #network do
+    if bits <= 0 then return true end
+    if bits >= 8 then
+      if bytes[i] ~= network[i] then return false end
+      bits = bits - 8
+    else
+      local div = 2 ^ (8 - bits)
+      return math.floor(bytes[i] / div) == math.floor(network[i] / div)
+    end
+  end
+  return true
+end
+
+--- Compile CIDR strings into { bytes, bits, version } entries.
+function M.compile(list)
+  local out = {}
+  for _, cidr in ipairs(list) do
+    local addr, bits = cidr:match("^(.-)/(%d+)$")
+    local bytes, version = M.parse(addr or cidr)
+    if not bytes then error("invalid CIDR: " .. tostring(cidr)) end
+    out[#out + 1] = { bytes = bytes, bits = tonumber(bits) or (#bytes * 8), version = version }
+  end
+  return out
+end
+
+M.RESERVED = M.compile({
+  -- IPv4
+  "0.0.0.0/8", "10.0.0.0/8", "100.64.0.0/10", "127.0.0.0/8", "169.254.0.0/16",
+  "172.16.0.0/12", "192.0.0.0/24", "192.0.2.0/24", "192.88.99.0/24", "192.168.0.0/16",
+  "198.18.0.0/15", "198.51.100.0/24", "203.0.113.0/24", "224.0.0.0/4", "240.0.0.0/4",
+  -- IPv6
+  "::/128", "::1/128", "100::/64", "2001::/23", "2001:db8::/32", "fc00::/7",
+  "fe80::/10", "fec0::/10", "ff00::/8",
+})
+
+local function embedded_v4(bytes)
+  -- ::ffff:a.b.c.d (mapped), ::a.b.c.d (compatible), 64:ff9b::a.b.c.d (NAT64)
+  local zero10 = true
+  for i = 1, 10 do
+    if bytes[i] ~= 0 then zero10 = false break end
+  end
+  if zero10 and ((bytes[11] == 255 and bytes[12] == 255) or (bytes[11] == 0 and bytes[12] == 0)) then
+    return { bytes[13], bytes[14], bytes[15], bytes[16] }
+  end
+  if bytes[1] == 0 and bytes[2] == 0x64 and bytes[3] == 0xff and bytes[4] == 0x9b then
+    return { bytes[13], bytes[14], bytes[15], bytes[16] }
+  end
+  -- 2002:AABB:CCDD::/48 (6to4)
+  if bytes[1] == 0x20 and bytes[2] == 0x02 then
+    return { bytes[3], bytes[4], bytes[5], bytes[6] }
+  end
+  return nil
+end
+
+--- Is the address private, loopback, link-local, multicast or otherwise reserved?
+function M.is_reserved(bytes, version)
+  for _, net in ipairs(M.RESERVED) do
+    if net.version == version and M.in_cidr(bytes, net.bytes, net.bits) then return true end
+  end
+  if version == 6 then
+    local v4 = embedded_v4(bytes)
+    if v4 then return M.is_reserved(v4, 4) end
+  end
+  return false
+end
+
+--- Canonical text form (IPv6 uncompressed), suitable for nginx proxy_pass.
+function M.to_string(bytes, version)
+  if version == 4 then
+    return string.format("%d.%d.%d.%d", bytes[1], bytes[2], bytes[3], bytes[4])
+  end
+  local groups = {}
+  for i = 1, 16, 2 do
+    groups[#groups + 1] = string.format("%x", bytes[i] * 256 + bytes[i + 1])
+  end
+  return table.concat(groups, ":")
+end
+
+return M

package/server/lua/butter/limit.lua

@@ -0,0 +1,18 @@
+-- Fixed-window rate limiter per client address.
+
+local M = {}
+
+--- @return boolean  true if the request may proceed
+function M.check(cfg)
+  if not cfg or not cfg.enabled then return true end
+  local window = cfg.window
+  local key = ngx.var.binary_remote_addr .. ":" .. math.floor(ngx.now() / window)
+  local count, err = ngx.shared.butter_limit:incr(key, 1, 0, window)
+  if not count then
+    ngx.log(ngx.WARN, "butter: rate limiter unavailable: ", err)
+    return true
+  end
+  return count <= cfg.requests
+end
+
+return M

package/server/lua/butter/session.lua

@@ -0,0 +1,42 @@
+-- Browser sessions: a random id in an HttpOnly cookie on the proxy origin
+-- keys the server-side cookie jar.
+
+local config = require "butter.config"
+
+local M = {}
+
+M.COOKIE = "butter_sid"
+
+--- @return string, boolean  session id, and whether it was just created
+function M.get()
+  local sid = ngx.var["cookie_" .. M.COOKIE]
+  if sid and #sid == 32 and sid:match("^%x+$") then return sid, false end
+  local random = require "resty.random"
+  local str = require "resty.string"
+  local bytes = random.bytes(16, true) or random.bytes(16)
+  return str.to_hex(bytes), true
+end
+
+--- Set-Cookie value for the session cookie.
+function M.cookie(sid)
+  local parts = {
+    M.COOKIE .. "=" .. sid,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Strict",
+    "Max-Age=" .. string.format("%d", config.get().cookies.session_ttl),
+  }
+  if ngx.var.scheme == "https" or ngx.var.http_x_forwarded_proto == "https" then
+    parts[#parts + 1] = "Secure"
+  end
+  return table.concat(parts, "; ")
+end
+
+--- Issue the session cookie on the current response if the request had none.
+function M.ensure()
+  local sid, created = M.get()
+  if created then ngx.header["Set-Cookie"] = M.cookie(sid) end
+  return sid, created
+end
+
+return M

package/server/lua/butter/store.lua

@@ -0,0 +1,77 @@
+-- Cookie jar storage: one JSON list per session in a shared dict.
+
+local cjson = require "cjson.safe"
+local jar = require "butter.cookiejar"
+local config = require "butter.config"
+
+local M = {}
+
+local function dict()
+  return ngx.shared.butter_cookies
+end
+
+local function load(sid)
+  local raw = dict():get("jar:" .. sid)
+  if not raw then return {} end
+  local list = cjson.decode(raw)
+  return type(list) == "table" and list or {}
+end
+
+local function save(sid, list)
+  local key = "jar:" .. sid
+  if #list == 0 then
+    dict():delete(key)
+    return
+  end
+  local ok, err, forcible = dict():set(key, cjson.encode(list), config.get().cookies.session_ttl)
+  if not ok then
+    ngx.log(ngx.ERR, "butter: cannot store cookies: ", err)
+  elseif forcible then
+    ngx.log(ngx.WARN, "butter: butter_cookies is full; evicting old sessions (consider a larger lua_shared_dict)")
+  end
+end
+
+-- Header filters cannot yield, so resty.lock is out. A short spin on an
+-- add()-based lock covers the rare case of two workers updating the same
+-- session at the same instant; on timeout we proceed anyway.
+local function with_lock(sid, fn)
+  local key = "lock:" .. sid
+  local locked = false
+  for _ = 1, 500 do
+    if dict():add(key, true, 0.05) then
+      locked = true
+      break
+    end
+  end
+  local ok, err = pcall(fn)
+  if locked then dict():delete(key) end
+  if not ok then ngx.log(ngx.ERR, "butter: cookie store error: ", err) end
+end
+
+--- Store Set-Cookie values received from (or written by scripts for) `target`.
+function M.set_cookies(sid, target, values, opts)
+  local now = ngx.time()
+  local max = config.get().cookies.max_per_session
+  with_lock(sid, function()
+    local list = load(sid)
+    for _, value in ipairs(values) do
+      local cookie = jar.parse_set_cookie(value, target, now)
+      if cookie then
+        list = jar.upsert(list, cookie, now, { from_script = opts and opts.from_script, max = max })
+      end
+    end
+    save(sid, list)
+  end)
+end
+
+--- Cookie request header for `target`.
+function M.cookie_header(sid, target)
+  return jar.header(load(sid), target, ngx.time())
+end
+
+--- What document.cookie should return for a page at `target`.
+function M.document_cookie(sid, target)
+  return jar.header(load(sid), target, ngx.time(), { for_script = true })
+end
+
+return M