Jitsi Meet - Secure, Simple and Scalable Video Conferences that you use as a standalone app or embed in your web application.
TypeScript debiandeep-videojitsijitsi-meetscalable-video-conferencessfuvideovideo-communicationvideo-conferencingwebrtc
-- Unit tests for mod_voice_agent_component.lua
-- Run with busted from resources/prosody-plugins/:
-- busted ../../tests/prosody/lua/
--
-- Stubs every Prosody dependency so no Prosody installation is needed. These focus on the
-- security-relevant validation at the provisioning boundary: ASAP auth, agentId namespacing (the
-- reserved "agent-" prefix that makes an agent id un-collidable with a real 8-hex endpoint id),
-- prototype-pollution key rejection, string-map bounds, prosody-only dial-config segregation — and the
-- v1 contract additions: idempotent invite, get, the state lifecycle, and signed webhooks.
-- End-to-end behaviour against a real Prosody is covered by the integration specs.
-- ---------------------------------------------------------------------------
-- Stubs for top-level `require`d Prosody libs (no Prosody install under busted)
-- ---------------------------------------------------------------------------
package.preload['util.hashes'] = function()
return {
-- Generated agent ids hash the random bytes; anything else (a token) hashes to its own key.
sha256 = function(data)
if data == 'xxxxxxxx' then return 'deadbeefcafef00d'; end
return (tostring(data):gsub('.', function(c) return string.format('%02x', c:byte()); end));
end,
hmac_sha256 = function(_key, data, _hex) return 'h:' .. data end
};
end
-- util.cache: a plain map per cache, every one registered so each test starts empty.
local caches = {};
package.preload['util.cache'] = function()
return { new = function()
local entries = {};
table.insert(caches, entries);
return { get = function(_, k) return entries[k]; end, set = function(_, k, v) entries[k] = v; end };
end };
end
package.preload['util.random'] = function()
return { bytes = function() return 'xxxxxxxx' end };
end
package.preload['util.http'] = function()
return {
formdecode = function(query)
local params = {};
for k, v in (query or ''):gmatch('([^&=]+)=([^&]*)') do params[k] = v; end
return params;
end
};
end
-- net.http: captures outbound webhook requests; `http_next_code` is the status the stub reports back.
local http_requests = {};
local metadata_events = 0;
local http_next_code = 200;
package.preload['net.http'] = function()
return {
request = function(url, ex, callback)
table.insert(http_requests, { url = url, ex = ex });
if callback then callback('', http_next_code, {}); end
return true;
end
};
end
-- cjson.safe: decode returns the per-test `next_decoded` table; encode records every table it is
-- given so tests can inspect response and webhook payloads without a real JSON parser.
local next_decoded;
local encoded = {};
package.preload['cjson.safe'] = function()
return {
decode = function(s)
if s == nil or s == '' then
return nil, 'empty';
end
return next_decoded;
end,
encode = function(t)
if type(t) == 'string' then return '"' .. t .. '"'; end
table.insert(encoded, t);
return '{}';
end
};
end
-- ---------------------------------------------------------------------------
-- Controllable stub state
-- ---------------------------------------------------------------------------
local token_valid = true;
-- The claims a verified token carries, as token/util puts them on the session, and what verify_room answers.
local token_room, token_sub = '*', '*';
-- context.tenant on the token, if any.
local token_tenant = nil;
-- true/false, or a function(session, room_address) answering allowed, reason.
local verify_room_ok = true;
local verify_room_calls = {};
-- What the module asked of set_asap_require_room_claim, in load order.
local require_room_claim_calls = {};
-- A breakout room the room lookups return for its JID, when a test sets one.
local breakout_room = nil;
-- Room JIDs the lookups no longer find, as after a room is destroyed.
local gone_rooms = {};
local mock_room;
local timers = {};
local host_hooks = {};
-- The same hooks keyed by the host they were installed on (the module hooks the main and breakout MUC hosts).
local host_hooks_by_host = {};
-- module:log calls, as { level, text }.
local logs = {};
-- Module events the module fires (module:fire_event); `fire_event_error` makes the next hook fail.
local module_events = {};
local fire_event_error = false;
-- module:shared() tables by path, kept across loads of the file so two loads act as two host instances.
local shared_store = {};
-- Public room-name lookups ({ name, subdomain }) seen by the util stub.
local name_lookups = {};
local util_stub = {
async_handler_wrapper = function(event, handler) return handler(event); end,
extract_subdomain = function(node)
local subdomain, room = node:match('^%[([^%]]+)%](.+)$');
return subdomain, room or node;
end,
get_room_by_name_and_subdomain = function(name, subdomain)
table.insert(name_lookups, { name = name, subdomain = subdomain });
if name == 'missing' then return nil; end
return mock_room;
end,
get_room_from_jid = function(jid)
if jid == 'missing' or gone_rooms[jid] then return nil; end
if breakout_room and jid == breakout_room.jid then return breakout_room; end
return mock_room;
end,
is_healthcheck_room = function(_) return false; end,
process_host_module = function(host, cb)
host_hooks_by_host[host] = host_hooks_by_host[host] or {};
cb({ hook = function(_, name, fn)
host_hooks[name] = fn;
host_hooks_by_host[host][name] = fn;
end; fire_event = function(_, name)
if name == 'room-metadata-changed' then metadata_events = metadata_events + 1; end
end });
end,
room_jid_match_rewrite = function(jid) return jid; end,
starts_with = function(s, prefix) return type(s) == 'string' and s:sub(1, #prefix) == prefix; end,
table_shallow_copy = function(t)
local c = {};
for k, v in pairs(t or {}) do c[k] = v; end
return c;
end
};
-- util.async: a runner that, like Prosody's, calls its function only for input given to run(), and a waiter that,
-- like Prosody's, fails outside a runner.
local in_runner = false;
package.preload['util.async'] = function()
return {
runner = function(fn)
return {
run = function(_, input)
if input == nil then
return;
end
in_runner = true;
local ok, err = pcall(fn, input);
in_runner = false;
if not ok then error(err, 0); end
end
};
end,
waiter = function()
if not in_runner then
error('Not running in an async context');
end
return function() end, function() end;
end
};
end
-- Whether the token's signing key is in the key cache; when not, verifying it fetches the key, which waits.
local key_cached = true;
local token_util_stub = {
new = function()
return {
enableDomainVerification = true,
requireRoomClaim = false,
set_asap_key_server = function() end,
set_asap_require_room_claim = function(_, required)
table.insert(require_room_claim_calls, required);
end,
process_and_verify_token = function(_, session)
if not key_cached then
require('util.async').waiter();
end
session.jitsi_meet_room = token_room;
session.jitsi_meet_domain = token_sub;
session.jitsi_meet_str_tenant = token_tenant;
return token_valid, 'reason', 'msg';
end,
verify_room = function(_, session, room_address)
table.insert(verify_room_calls, {
room = room_address; token_room = session.jitsi_meet_room; prefix = session.jitsi_web_query_prefix });
if type(verify_room_ok) == 'function' then return verify_room_ok(session, room_address); end
if verify_room_ok then return true; end
return false, 'room-mismatch', 'Room does not match the room from token';
end
};
end
};
-- Captured HTTP route handlers, filled by the module:provides stub below.
local routes = {};
-- Option values the module is loaded with; a test may reload it with overrides (see "alternate configurations").
local option_overrides = {};
local function option(key, default)
if option_overrides[key] ~= nil then return option_overrides[key]; end
if key == 'muc_component' then return 'conference.localhost'; end
if key == 'breakout_rooms_component' then return 'breakout.localhost'; end
if key == 'voice_agent_webhook_secret' then return 'shh'; end
if key == 'voice_agent_status_secret' then return 'jicofo-secret'; end
if key == 'voice_agent_dial_secret' then return 'relay-secret'; end
if key == 'prosody_password_public_key_repo_url' then return 'https://keys.example.com/'; end
if key == 'muc_mapper_domain_base' then return 'localhost'; end
if key == 'voice_agent_callback_allowed_hosts' then return { 'app.example.com' }; end
return default;
end
-- The main MUC service the module searches for a breakout room's main room: it holds the current mock room.
_G.prosody = { hosts = { ['conference.localhost'] = { modules = { muc = {
each_room = function()
local done = false;
return function()
if done then return nil; end
done = true;
return mock_room;
end;
end
} } } } };
_G.module = {
host = 'voiceagent.localhost',
fire_event = function(_, name, event)
table.insert(module_events, { name = name, event = event });
if fire_event_error then error('hook failed'); end
end,
shared = function(_, path)
shared_store[path] = shared_store[path] or {};
return shared_store[path];
end,
log = function(_, level, fmt, ...)
local ok, text = pcall(string.format, fmt, ...);
table.insert(logs, { level = level, text = ok and text or fmt });
end,
get_option_string = function(_, key, default) return option(key, default); end,
get_option_number = function(_, key, default) return option(key, default); end,
get_option_boolean = function(_, key, default) return option(key, default); end,
get_option_array = function(_, key, default) return option(key, default or {}); end,
measure = function() return function() end; end,
depends = function() end,
add_timer = function(_, delay, fn) table.insert(timers, { delay = delay, fn = fn }); end,
require = function(_, name)
if name == 'util' then return util_stub; end
if name == 'token/util' then return token_util_stub; end
return {};
end,
provides = function(_, _kind, def)
for name, handler in pairs(def.route) do routes[name] = handler; end
end
};
-- ---------------------------------------------------------------------------
-- Load the module under test
-- ---------------------------------------------------------------------------
local ok, load_err = pcall(dofile, 'mod_voice_agent_component.lua');
if not ok then
describe('mod_voice_agent_component', function()
it('skipped — failed to load module', function()
pending(tostring(load_err):match('([^\n]+)') or tostring(load_err));
end)
end)
return;
end
for _, route in ipairs({ 'POST voice-agent/invite', 'POST voice-agent/dismiss', 'GET voice-agent/list',
'GET voice-agent/get', 'POST voice-agent/status', 'GET voice-agent/dial',
'GET voice-agent/events' }) do
assert(routes[route], route .. ' route not registered');
end
-- ---------------------------------------------------------------------------
-- Test helpers
-- ---------------------------------------------------------------------------
local function fresh_room()
return {
jid = '[email protected]';
jitsiMetadata = {};
_data = {};
occupants = {};
each_occupant = function(self)
local i = 0;
return function()
i = i + 1;
local occupant = self.occupants[i];
if occupant then
return occupant.nick, occupant;
end
end;
end;
};
end
-- An occupant whose presence carries the given jitsi_participant_* properties.
local function occupant(props)
return {
nick = '[email protected]/p' .. tostring(math.random(1e6));
get_presence = function()
return { get_child_text = function(_, name) return props[name]; end };
end;
};
end
local function post(route, payload, opts)
opts = opts or {};
next_decoded = payload;
local headers = { content_type = 'application/json' };
if not opts.omitAuth then
headers.authorization = opts.token or 'Bearer sometoken';
end
return routes[route]({ request = { headers = headers; body = 'x' } });
end
local DEFAULT_ENDPOINT = { url = 'wss://agents.example.com/s' };
-- Every invite needs an endpoint; tests that do not care get the default one.
local function invite(payload, opts)
opts = opts or {};
if payload.endpoint == nil and not opts.noEndpoint then
payload.endpoint = DEFAULT_ENDPOINT;
end
return post('POST voice-agent/invite', payload, opts);
end
local function dismiss(payload, opts) return post('POST voice-agent/dismiss', payload, opts); end
local function status(payload, opts) return post('POST voice-agent/status', payload, opts); end
local function get(query, opts)
opts = opts or {};
return routes['GET voice-agent/get']({
request = { headers = { authorization = opts.token or 'Bearer t' }; url = { query = query } } });
end
local function list(query, opts)
opts = opts or {};
return routes['GET voice-agent/list']({
request = { headers = { authorization = opts.token or 'Bearer t' }; url = { query = query } } });
end
local function dial(query, opts)
opts = opts or {};
local headers = {};
if not opts.omitAuth then
headers.authorization = opts.token or 'Bearer t';
end
return routes['GET voice-agent/dial']({ request = { headers = headers; url = { query = query } } });
end
local function agent_ids(room)
local ids = {};
for id in pairs(room.jitsiMetadata.agents or {}) do table.insert(ids, id); end
return ids;
end
-- Every recorded webhook payload of the given event type, in emission order.
local function webhook_payloads(event_name)
local out = {};
for _, t in ipairs(encoded) do
if type(t) == 'table' and t.event == event_name then table.insert(out, t); end
end
return out;
end
local CALLBACK = 'https://app.example.com/agent-events';
-- A Prosody-shaped response object for the event stream: records every write and behaves like
-- net.http.server on done()/on_destroy().
local function sse_response()
local response = { status_code = 200; headers = {}; finished = false; writes = {} };
response.conn = { write = function(_, data) table.insert(response.writes, data); end };
response.write_headers = function(self) self.headers_written = true; end;
response.done = function(self)
self.finished = true;
if self.on_destroy then self:on_destroy(); self.on_destroy = nil; end
end;
-- A plain response, as a refused request gets.
response.send = function(self, body)
self.sent = body or '';
self.finished = true;
end;
-- What net.http.server does when the client goes away.
response.disconnect = function(self)
self.finished = true;
if self.on_destroy then self:on_destroy(); end
end;
return response;
end
-- Streams opened by the current test, disconnected before the next one so module state does not leak.
local open_streams = {};
-- Opens an event stream; returns the handler's result and the response it wrote to.
local function events(query, opts)
opts = opts or {};
local headers = {};
if not opts.omitAuth then headers.authorization = opts.token or 'Bearer t'; end
if opts.lastEventId then headers.last_event_id = opts.lastEventId; end
local response = sse_response();
table.insert(open_streams, response);
local result = routes['GET voice-agent/events']({
request = { headers = headers; url = { query = query } }; response = response });
-- The route takes every request over; a refusal is sent on the response.
if response.sent ~= nil then
return { status_code = response.status_code; body = response.sent }, response;
end
return result, response;
end
-- The SSE events a stream received, in order, as { id, event }; keepalive comments as { comment = true }.
local function stream_events(response)
local out = {};
for _, w in ipairs(response.writes) do
local text = w:match('^%x+\r\n(.*)\r\n$');
if text and text:sub(1, 1) == ':' then
table.insert(out, { comment = true });
elseif text then
table.insert(out, { id = text:match('id: ([^\n]+)'); event = text:match('event: ([^\n]+)') });
end
end
return out;
end
-- The data line of the last snapshot frame a stream received (every table in it encodes as {} under the stub).
local function snapshot_data(response)
local data;
for _, w in ipairs(response.writes) do
local text = w:match('^%x+\r\n(.*)\r\n$');
if text and text:find('event: snapshot', 1, true) then
data = text:match('data: ([^\n]*)');
end
end
return data;
end
-- The agents the module encoded for snapshots (client fields plus `conference`), in order.
local function snapshot_agents()
local out = {};
for _, t in ipairs(encoded) do
if type(t) == 'table' and t.agentId and t.conference and t.displayName and not t.event then
table.insert(out, t);
end
end
return out;
end
-- ---------------------------------------------------------------------------
-- Tests
-- ---------------------------------------------------------------------------
describe('mod_voice_agent_component', function()
before_each(function()
for _, response in ipairs(open_streams) do response:disconnect(); end
open_streams = {};
-- With every stream gone, a pending keepalive tick disarms itself, so the next test gets a fresh timer.
for _, timer in ipairs(timers) do
if timer.delay == 15 then pcall(timer.fn); end
end
token_valid = true;
token_room, token_sub = '*', '*';
token_tenant = nil;
verify_room_ok = true;
verify_room_calls = {};
breakout_room = nil;
gone_rooms = {};
for _, entries in ipairs(caches) do
for k in pairs(entries) do entries[k] = nil; end
end
mock_room = fresh_room();
http_requests = {};
metadata_events = 0;
http_next_code = 200;
timers = {};
name_lookups = {};
logs = {};
module_events = {};
fire_event_error = false;
key_cached = true;
in_runner = false;
for i = #encoded, 1, -1 do encoded[i] = nil; end
-- The module remembers rooms with agents by weak key: collect the previous test's room.
collectgarbage('collect');
end)
describe('public room names (no MUC JIDs for customers)', function()
it('resolves <tenant>/<room>, lower-cased, through the tenant', function()
assert.are.equal(200, invite({ conference = 'Acme/Support-Room'; displayName = 'Bot' }).status_code);
assert.are.same({ name = 'support-room', subdomain = 'acme' }, name_lookups[1]);
end)
it('resolves a bare <room> outside any tenant', function()
assert.are.equal(200, invite({ conference = 'lobby'; displayName = 'Bot' }).status_code);
assert.are.same({ name = 'lobby' }, name_lookups[1]);
end)
it('also takes a room JID, without a name lookup', function()
assert.are.equal(200, invite({ conference = '[email protected]'; displayName = 'Bot';
agentId = 'support' }).status_code);
assert.are.equal(200, dismiss({ conference = '[email protected]'; agentId = 'agent-support' }).status_code);
assert.are.equal(0, #name_lookups);
end)
it('takes conference and breakout room JIDs, not a lobby room\'s', function()
assert.are.equal(200, invite({ conference = '[email protected]'; displayName = 'Bot';
agentId = 'support' }).status_code);
assert.are.equal(200, dial('[email protected]&agentId=agent-support').status_code);
assert.are.equal(404, invite({ conference = '[email protected]'; displayName = 'Bot' }).status_code);
assert.are.equal(404, dial('[email protected]&agentId=agent-support').status_code);
end)
it('spells names as the client stores them, from the plain or the encoded form', function()
local cases = {
{ 'Sales Standup', 'sales%20standup' },
{ 'sales%20STANDUP', 'sales%20standup' },
{ 'Caf\195\169', 'caf%c3%a9' },
{ 'caf%C3%A9', 'caf%c3%a9' },
{ 'a+b', 'a%2bb' },
{ '100%', '100%25' },
{ '[t]room', '%5bt%5droom' },
};
for i, case in ipairs(cases) do
invite({ conference = case[1]; displayName = 'Bot' });
assert.are.equal(case[2], name_lookups[i].name, case[1]);
end
end)
it('rejects names with more than one tenant segment or an empty one', function()
for _, bad in ipairs({ 'a/b/c', '/room', 'tenant/' }) do
assert.are.equal(404, invite({ conference = bad; displayName = 'Bot' }).status_code, bad);
end
end)
it('masks internal addresses in a failure reason before it reaches the webhook', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed';
reason = 'bridge allocation failed: Session no longer active ([email protected]/jvb-1)' },
{ token = 'Bearer jicofo-secret' });
assert.are.equal('bridge allocation failed: Session no longer active <internal>',
webhook_payloads('agent.failed')[1].reason);
end)
it('names the room <tenant>/<room> in webhooks and the dial response, never by JID', function()
mock_room.jid = '[acme][email protected]';
invite({ conference = 'acme/support'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
status({ conference = '[acme][email protected]'; agentId = 'agent-support'; state = 'active' },
{ token = 'Bearer jicofo-secret' });
assert.are.equal('acme/support', webhook_payloads('agent.connected')[1].conference);
dial('conference=[acme][email protected]&agentId=agent-support');
assert.are.equal('acme/support', encoded[#encoded].conference);
end)
it('names a room outside any tenant by its bare name', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
dismiss({ conference = 'r'; agentId = 'agent-support' });
assert.are.equal('room1', webhook_payloads('agent.ended')[1].conference);
end)
end)
describe('authentication', function()
it('returns 401 when the Authorization header is absent', function()
local res = invite({ conference = 'r'; displayName = 'Bot' }, { omitAuth = true });
assert.are.equal(401, res.status_code);
end)
it('returns 401 when the token does not verify', function()
token_valid = false;
local res = invite({ conference = 'r'; displayName = 'Bot' });
assert.are.equal(401, res.status_code);
end)
end)
describe('agentId namespacing (collision prevention)', function()
it('generates an agent- prefixed id when none is provided', function()
local res = invite({ conference = 'r'; displayName = 'Bot' });
assert.are.equal(200, res.status_code);
local ids = agent_ids(mock_room);
assert.are.equal(1, #ids);
assert.is_truthy(ids[1]:match('^agent%-'), 'generated id must be agent- prefixed: ' .. ids[1]);
end)
it('normalizes a bare (endpoint-id-shaped) agentId into the agent- namespace', function()
-- '1a2b3c4d' is exactly the shape of a real participant endpoint id.
invite({ conference = 'r'; displayName = 'Bot'; agentId = '1a2b3c4d' });
assert.is_truthy(mock_room.jitsiMetadata.agents['agent-1a2b3c4d'],
'a bare id must be namespaced so it cannot collide with a real endpoint id');
assert.is_nil(mock_room.jitsiMetadata.agents['1a2b3c4d']);
end)
it('is idempotent when the agentId already carries the prefix', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'agent-support' });
assert.is_truthy(mock_room.jitsiMetadata.agents['agent-support']);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-agent-support']);
end)
it('derives the source name from the namespaced id', function()
local res = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal('agent-support-a0', mock_room.jitsiMetadata.agents['agent-support'].sourceName);
-- The 200 body echoes the same source name (encode is stubbed, so just assert success).
assert.are.equal(200, res.status_code);
end)
end)
describe('prototype-pollution key rejection', function()
for _, bad in ipairs({ '__proto__', 'constructor', 'prototype' }) do
it('rejects agentId "' .. bad .. '"', function()
local res = invite({ conference = 'r'; displayName = 'Bot'; agentId = bad });
assert.are.equal(400, res.status_code);
assert.are.equal(0, #agent_ids(mock_room));
end)
end
end)
describe('agentId charset and length', function()
it('rejects an agentId with disallowed characters', function()
assert.are.equal(400, invite({ conference = 'r'; displayName = 'B'; agentId = 'a b/c' }).status_code);
end)
it('rejects an over-long agentId suffix', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B'; agentId = string.rep('a', 49) }).status_code);
end)
end)
describe('required fields and limits', function()
it('returns 400 when displayName is missing', function()
assert.are.equal(400, invite({ conference = 'r' }).status_code);
end)
it('returns 404 when the room does not exist', function()
assert.are.equal(404, invite({ conference = 'missing'; displayName = 'B' }).status_code);
end)
it('enforces the per-room agent cap', function()
for i = 1, 5 do
assert.are.equal(200, invite({ conference = 'r'; displayName = 'B'; agentId = 'a' .. i }).status_code);
end
assert.are.equal(409, invite({ conference = 'r'; displayName = 'B'; agentId = 'a6' }).status_code);
end)
end)
describe('customParameters validation', function()
it('rejects a non-string map value', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B'; customParameters = { k = 5 } }).status_code);
end)
it('rejects too many entries', function()
local big = {};
for i = 1, 17 do big['k' .. i] = 'v'; end
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B'; customParameters = big }).status_code);
end)
it('rejects a value with control characters', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B';
customParameters = { X = 'a\r\nX-Injected: 1' } }).status_code);
end)
it('rejects an over-long key', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B';
customParameters = { [string.rep('k', 129)] = 'v' } }).status_code);
end)
end)
describe('endpoint', function()
it('is required', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B' }, { noEndpoint = true }).status_code);
end)
it('rejects a non-wss endpoint.url', function()
assert.are.equal(400, invite({
conference = 'r'; displayName = 'B'; endpoint = { url = 'http://evil/s' }
}).status_code);
end)
it('rejects an endpoint.authorization with control characters', function()
assert.are.equal(400, invite({ conference = 'r'; displayName = 'B';
endpoint = { url = 'wss://agents.example.com/s'; authorization = 'Bearer k\r\nX: 1' } }).status_code);
end)
it('keeps the endpoint and its secret out of the client-facing entry', function()
invite({
conference = 'r';
displayName = 'Bot';
agentId = 'support';
endpoint = { url = 'wss://agents.example.com/s'; authorization = 'Bearer k' }
});
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support'].endpoint);
local stored = mock_room._data.voice_agents['agent-support'].endpoint;
assert.are.equal('wss://agents.example.com/s', stored.url);
assert.are.equal('Bearer k', stored.authorization);
end)
end)
describe('end-to-end encryption', function()
it('rejects an invite while anyone has end-to-end encryption on', function()
mock_room.occupants = { occupant({}), occupant({ ['jitsi_participant_e2ee.enabled'] = 'true' }) };
local res = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(409, res.status_code);
assert.are.equal('End-to-end encryption is on in this meeting', encoded[#encoded].error);
assert.are.equal(0, #agent_ids(mock_room));
end)
it('accepts the invite once encryption is off again', function()
mock_room.occupants = { occupant({ ['jitsi_participant_e2ee.enabled'] = 'false' }) };
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' }).status_code);
end)
it('still answers an identical re-invite of a present agent with 200', function()
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' }).status_code);
mock_room.occupants = { occupant({ ['jitsi_participant_e2ee.enabled'] = 'true' }) };
local res = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(200, res.status_code);
end)
it('reports a different re-invite as a conflict, not as encryption', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
mock_room.occupants = { occupant({ ['jitsi_participant_e2ee.enabled'] = 'true' }) };
local res = invite({ conference = 'r'; displayName = 'Other'; agentId = 'support' });
assert.are.equal(409, res.status_code);
assert.are.equal('agentId already exists with different parameters', encoded[#encoded].error);
end)
it('refuses to replace a failed agent, and keeps its record', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'no bridge' });
mock_room.occupants = { occupant({ ['jitsi_participant_e2ee.enabled'] = 'true' }) };
local res = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(409, res.status_code);
assert.are.equal('End-to-end encryption is on in this meeting', encoded[#encoded].error);
assert.are.equal('failed', mock_room.jitsiMetadata.agents['agent-support'].state);
end)
end)
describe('mediaFormat', function()
local function dial_body()
assert.are.equal(200, dial('conference=r&agentId=agent-support').status_code);
return encoded[#encoded];
end
it('defaults to PCM16 in the dial response', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal('audio/l16', dial_body().mediaFormat.encoding);
end)
it('carries Opus to the dial response and keeps it out of the client-facing entry', function()
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
mediaFormat = { encoding = 'audio/opus' } }).status_code);
assert.are.equal('audio/opus', dial_body().mediaFormat.encoding);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support'].mediaFormat);
end)
it('rejects an unknown encoding, a non-object and unsupported fields', function()
for _, bad in ipairs({ { encoding = 'audio/pcmu' }, 'audio/opus', {},
{ encoding = 'audio/l16'; sampleRate = 16000 } }) do
assert.are.equal(400, invite({ conference = 'r'; displayName = 'Bot'; mediaFormat = bad }).status_code);
end
assert.are.equal(0, #agent_ids(mock_room));
end)
it('is part of the idempotency check, the default matching an explicit audio/l16', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
mediaFormat = { encoding = 'audio/l16' } }).status_code);
-- A record from before mediaFormat existed counts as the default.
mock_room._data.voice_agents['agent-support'].mediaFormat = nil;
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' }).status_code);
assert.are.equal(409, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
mediaFormat = { encoding = 'audio/opus' } }).status_code);
end)
end)
describe('fanIn', function()
local function dial_body()
assert.are.equal(200, dial('conference=r&agentId=agent-support').status_code);
return encoded[#encoded];
end
it('defaults to per-source in the dial response', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal('per-source', dial_body().fanIn);
end)
it('carries dominant to the dial response and keeps it out of the client-facing entry', function()
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
fanIn = 'dominant' }).status_code);
assert.are.equal('dominant', dial_body().fanIn);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support'].fanIn);
end)
it('rejects an unknown policy and a non-string', function()
for _, bad in ipairs({ 'loudest', 'Dominant', 42, { 'dominant' } }) do
assert.are.equal(400, invite({ conference = 'r'; displayName = 'Bot'; fanIn = bad }).status_code);
end
assert.are.equal(0, #agent_ids(mock_room));
end)
it('is part of the idempotency check, the default matching an explicit per-source', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
fanIn = 'per-source' }).status_code);
-- A record from before fanIn existed counts as the default.
mock_room._data.voice_agents['agent-support'].fanIn = nil;
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' }).status_code);
assert.are.equal(409, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
fanIn = 'dominant' }).status_code);
end)
end)
describe('dial (internal, fetched by the media relay)', function()
local function invite_support()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
endpoint = { url = 'wss://agents.example.com/s'; authorization = 'Bearer k' };
customParameters = { campaign = '42' } });
end
it('returns the endpoint and custom parameters for the dial secret bearer', function()
invite_support();
local res = dial('conference=r&agentId=agent-support', { token = 'Bearer relay-secret' });
assert.are.equal(200, res.status_code);
local body = encoded[#encoded];
assert.are.equal('agent-support', body.agentId);
assert.are.equal('wss://agents.example.com/s', body.endpoint.url);
assert.are.equal('Bearer k', body.endpoint.authorization);
assert.are.equal('42', body.customParameters.campaign);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support'].customParameters);
end)
it('accepts an ASAP token too', function()
invite_support();
assert.are.equal(200, dial('conference=r&agentId=agent-support').status_code);
end)
it('refuses jicofo\'s status secret once a dial secret is configured, while status takes either', function()
invite_support();
token_valid = false;
assert.are.equal(401, dial('conference=r&agentId=agent-support', { token = 'Bearer jicofo-secret' }).status_code);
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'connecting' },
{ token = 'Bearer relay-secret' }).status_code);
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'active' },
{ token = 'Bearer jicofo-secret' }).status_code);
end)
it('rejects a missing or invalid token', function()
invite_support();
assert.are.equal(401, dial('conference=r&agentId=agent-support', { omitAuth = true }).status_code);
token_valid = false;
assert.are.equal(401, dial('conference=r&agentId=agent-support', { token = 'Bearer wrong' }).status_code);
end)
it('returns 404 for an unknown agent and for a missing room', function()
assert.are.equal(404, dial('conference=r&agentId=agent-nope').status_code);
assert.are.equal(404, dial('conference=missing&agentId=agent-support').status_code);
end)
end)
describe('idempotent invite', function()
it('returns the existing agent for an identical re-invite without duplicating it', function()
local first = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
customParameters = { a = '1' } });
local second = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
customParameters = { a = '1' } });
assert.are.equal(200, first.status_code);
assert.are.equal(200, second.status_code);
assert.are.equal(1, #agent_ids(mock_room));
end)
it('conflicts (409) when the same agentId is re-invited with different parameters', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(409, invite({ conference = 'r'; displayName = 'Other'; agentId = 'support' }).status_code);
assert.are.equal(409, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
customParameters = { a = '2' } }).status_code);
assert.are.equal('Bot', mock_room.jitsiMetadata.agents['agent-support'].displayName);
end)
end)
describe('state lifecycle', function()
it('starts an invited agent in the provisioning state', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal('provisioning', mock_room.jitsiMetadata.agents['agent-support'].state);
end)
it('advances to connecting without a webhook', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'connecting' }).status_code);
assert.are.equal('connecting', mock_room.jitsiMetadata.agents['agent-support'].state);
assert.are.equal(0, #http_requests);
end)
it('advances to active and fires agent.connected', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal('active', mock_room.jitsiMetadata.agents['agent-support'].state);
local connected = webhook_payloads('agent.connected');
assert.are.equal(1, #connected);
assert.are.equal('agent-support', connected[1].agentId);
assert.are.equal('active', connected[1].state);
end)
it('marks failed with a reason and fires agent.failed', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'dial refused' });
assert.are.equal('failed', mock_room.jitsiMetadata.agents['agent-support'].state);
local failed = webhook_payloads('agent.failed');
assert.are.equal(1, #failed);
assert.are.equal('dial refused', failed[1].reason);
end)
it('tears the agent down on ended and fires agent.ended', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'ended' }).status_code);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support']);
assert.is_nil(mock_room._data.voice_agents['agent-support']);
assert.are.equal(1, #webhook_payloads('agent.ended'));
end)
it('rejects an unknown state', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(400, status({ conference = 'r'; agentId = 'agent-support'; state = 'dancing' }).status_code);
end)
it('returns 404 for an unknown agent', function()
assert.are.equal(404, status({ conference = 'r'; agentId = 'agent-nope'; state = 'active' }).status_code);
end)
end)
describe('get', function()
it('returns the client-facing agent', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local res = get('conference=r&agentId=agent-support');
assert.are.equal(200, res.status_code);
local body = encoded[#encoded];
assert.are.equal('agent-support', body.agentId);
assert.are.equal('agent-support-a0', body.sourceName);
assert.are.equal('provisioning', body.state);
end)
it('returns 404 for an unknown agent and for a missing room', function()
assert.are.equal(404, get('conference=r&agentId=agent-nope').status_code);
assert.are.equal(404, get('conference=missing&agentId=agent-support').status_code);
end)
end)
describe('callbackUrl and webhooks', function()
it('rejects a non-https callbackUrl', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B'; callbackUrl = 'http://app.example.com/hook' }).status_code);
end)
it('stores callbackUrl jicofo-only, never in the client-facing entry', function()
invite({ conference = 'r'; displayName = 'B'; agentId = 'support'; callbackUrl = CALLBACK });
assert.are.equal(CALLBACK, mock_room._data.voice_agents['agent-support'].callbackUrl);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support'].callbackUrl);
end)
it('sends no webhook when the agent has no callbackUrl', function()
invite({ conference = 'r'; displayName = 'B'; agentId = 'support' });
dismiss({ conference = 'r'; agentId = 'agent-support' });
assert.are.equal(0, #http_requests);
end)
it('POSTs a signed agent.ended webhook on dismiss', function()
invite({ conference = 'r'; displayName = 'B'; agentId = 'support'; callbackUrl = CALLBACK });
dismiss({ conference = 'r'; agentId = 'agent-support' });
assert.are.equal(1, #http_requests);
local req = http_requests[1];
assert.are.equal(CALLBACK, req.url);
assert.are.equal('POST', req.ex.method);
assert.are.equal('application/json', req.ex.headers['Content-Type']);
assert.are.equal('sha256=h:{}', req.ex.headers['X-Agent-Signature']);
local ended = webhook_payloads('agent.ended');
assert.are.equal(1, #ended);
assert.are.equal('agent-support', ended[1].agentId);
assert.are.equal('ended', ended[1].state);
assert.are.equal('dismissed', ended[1].reason);
assert.is_truthy(ended[1].timestamp);
end)
it('retries a failed delivery with backoff', function()
http_next_code = 500;
invite({ conference = 'r'; displayName = 'B'; agentId = 'support'; callbackUrl = CALLBACK });
dismiss({ conference = 'r'; agentId = 'agent-support' });
assert.are.equal(1, #http_requests);
assert.are.equal(1, #timers, 'first failure must schedule a retry');
timers[1].fn();
assert.are.equal(2, #http_requests);
assert.is_true(timers[2].delay > timers[1].delay, 'backoff must grow');
end)
it('fires agent.ended for every agent when the room is destroyed', function()
invite({ conference = 'r'; displayName = 'B'; agentId = 'one'; callbackUrl = CALLBACK });
invite({ conference = 'r'; displayName = 'B'; agentId = 'two'; callbackUrl = CALLBACK });
host_hooks['muc-room-destroyed']({ room = mock_room });
local ended = webhook_payloads('agent.ended');
assert.are.equal(2, #ended);
assert.are.equal('room-destroyed', ended[1].reason);
end)
it('sends agent.ended once per agent even when the destroy hook runs twice', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
host_hooks['muc-room-destroyed']({ room = mock_room });
host_hooks['muc-room-destroyed']({ room = mock_room });
assert.are.equal(1, #webhook_payloads('agent.ended'));
end)
end)
describe('voice-agent-lifecycle module event', function()
local function lifecycle_events()
local out = {};
for _, e in ipairs(module_events) do
if e.name == 'voice-agent-lifecycle' then table.insert(out, e.event); end
end
return out;
end
it('fires for connected and ended with the webhook payload, without a callbackUrl', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
dismiss({ conference = 'r'; agentId = 'agent-support' });
local events = lifecycle_events();
assert.are.equal(2, #events);
assert.are.equal(mock_room, events[1].room);
assert.are.equal('agent-support', events[1].agent_id);
assert.are.equal('agent.connected', events[1].payload.event);
assert.are.equal('active', events[1].payload.state);
assert.are.equal('agent-support-a0', events[1].payload.sourceName);
assert.is_truthy(events[1].payload.timestamp);
assert.are.equal('agent.ended', events[2].payload.event);
assert.are.equal('dismissed', events[2].payload.reason);
assert.are.equal(0, #http_requests, 'no callbackUrl, no webhook');
end)
it('fires one terminal event: a failed agent gets no ended event on dismiss', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'no bridge available' });
dismiss({ conference = 'r'; agentId = 'agent-support' });
local events = lifecycle_events();
assert.are.equal(1, #events);
assert.are.equal('agent.failed', events[1].payload.event);
assert.are.equal('no bridge available', events[1].payload.reason);
end)
it('fires on room destroy with the same payload as the webhook', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
host_hooks['muc-room-destroyed']({ room = mock_room });
local events = lifecycle_events();
assert.are.equal(1, #events);
assert.are.equal('room-destroyed', events[1].payload.reason);
assert.are.equal(events[1].payload, webhook_payloads('agent.ended')[1]);
end)
it('survives a failing hook: the transition and the webhook still happen', function()
fire_event_error = true;
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
local res = status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal(200, res.status_code);
assert.are.equal('active', mock_room.jitsiMetadata.agents['agent-support'].state);
assert.are.equal(1, #http_requests);
local warned = false;
for _, entry in ipairs(logs) do
if entry.level == 'warn' and entry.text:find('voice-agent-lifecycle', 1, true) then warned = true; end
end
assert.is_true(warned, 'a failing hook must be logged');
end)
end)
describe('event stream (GET /voice-agent/events)', function()
it('verifies the token in an async runner, so a key that is not cached yet does not fail the stream', function()
key_cached = false;
local result, response = events('conference=r');
assert.is_true(result);
assert.are.equal('text/event-stream', response.headers.content_type);
assert.are.equal('snapshot', stream_events(response)[1].event);
end)
it('requires authorization', function()
local result, response = events('conference=r', { omitAuth = true });
assert.are.equal(401, result.status_code);
assert.are.equal(0, #response.writes);
end)
it('opens a chunked text/event-stream and starts with a snapshot of the agents in scope', function()
invite({ conference = 'r'; displayName = 'A'; agentId = 'one' });
invite({ conference = 'r'; displayName = 'B'; agentId = 'two' });
status({ conference = 'r'; agentId = 'agent-two'; state = 'active' });
local result, response = events('conference=r');
assert.is_true(result);
assert.is_true(response.headers_written);
assert.are.equal('text/event-stream', response.headers.content_type);
assert.are.equal('chunked', response.headers.transfer_encoding);
assert.are.equal('no', response.headers.x_accel_buffering);
local received = stream_events(response);
assert.are.equal(1, #received);
assert.are.equal('snapshot', received[1].event);
assert.are.equal('{"conference":"room1","agents":[{},{}]}', snapshot_data(response));
local agents = snapshot_agents();
assert.are.equal(2, #agents);
assert.are.equal('agent-one', agents[1].agentId);
assert.are.equal('provisioning', agents[1].state);
assert.are.equal('agent-two', agents[2].agentId);
assert.are.equal('active', agents[2].state);
assert.are.equal('room1', agents[2].conference);
assert.is_nil(agents[2].endpoint, 'a snapshot carries client fields only');
end)
it('writes each lifecycle event to the stream, with an opaque id', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, response = events('conference=r');
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
dismiss({ conference = 'r'; agentId = 'agent-support' });
local received = stream_events(response);
assert.are.equal(3, #received);
assert.are.equal('agent.connected', received[2].event);
assert.are.equal('agent.ended', received[3].event);
assert.is_truthy(received[2].id:match('^%x+%-%d+$'));
assert.are_not.equal(received[2].id, received[3].id);
end)
it('a stream for a room that does not exist yet gets an empty snapshot and no other room\'s events', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local result, response = events('conference=missing');
assert.is_true(result);
assert.are.equal('{"conference":"missing","agents":[]}', snapshot_data(response), 'an empty snapshot is still an array');
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal(1, #stream_events(response), 'room1 events stay out of a stream for another room');
end)
it('a stream without a conference covers every room', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, response = events(nil);
assert.are.equal('{"agents":[{}]}', snapshot_data(response));
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal('agent.connected', stream_events(response)[2].event);
end)
it('rejects a JID outside the conference hosts', function()
assert.are.equal(404, events('[email protected]').status_code);
end)
it('replays the events missed since a known Last-Event-ID instead of a snapshot', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, first = events('conference=r');
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
local connected_id = stream_events(first)[2].id;
first:disconnect();
dismiss({ conference = 'r'; agentId = 'agent-support' });
local _, second = events('conference=r', { lastEventId = connected_id });
local received = stream_events(second);
assert.are.equal(1, #received);
assert.are.equal('agent.ended', received[1].event);
end)
it('sends a snapshot when the Last-Event-ID is from another epoch', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, response = events('conference=r', { lastEventId = 'deadbeef-7' });
assert.are.equal('snapshot', stream_events(response)[1].event);
end)
it('forgets a stream whose client went away', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, response = events('conference=r');
response:disconnect();
local before = #response.writes;
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal(before, #response.writes);
end)
it('drops a room from the snapshot once its last agent is gone', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
dismiss({ conference = 'r'; agentId = 'agent-support' });
local _, response = events('conference=r');
assert.are.equal('{"conference":"room1","agents":[]}', snapshot_data(response));
end)
it('drops a destroyed room from the snapshot', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
host_hooks['muc-room-destroyed']({ room = mock_room });
local _, response = events(nil);
assert.are.equal('{"agents":[]}', snapshot_data(response));
end)
it('keeps the stream alive with a comment on each timer tick', function()
local _, response = events('conference=r');
assert.are.equal(15, timers[#timers].delay);
local again = timers[#timers].fn();
assert.are.equal(15, again, 'the keepalive re-arms itself while streams are open');
local received = stream_events(response);
assert.is_true(received[#received].comment);
end)
end)
describe('status route auth (jicofo shared secret)', function()
it('accepts the configured shared secret without an ASAP token', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
token_valid = false;
local res = status({ conference = 'r'; agentId = 'agent-support'; state = 'active' },
{ token = 'Bearer jicofo-secret' });
assert.are.equal(200, res.status_code);
assert.are.equal('active', mock_room.jitsiMetadata.agents['agent-support'].state);
end)
it('rejects a wrong shared secret', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
token_valid = false;
assert.are.equal(401, status({ conference = 'r'; agentId = 'agent-support'; state = 'active' },
{ token = 'Bearer nope' }).status_code);
end)
it('never lets the shared secret provision agents', function()
token_valid = false;
assert.are.equal(401, invite({ conference = 'r'; displayName = 'Bot' },
{ token = 'Bearer jicofo-secret' }).status_code);
end)
end)
describe('status lifecycle is forward-only', function()
before_each(function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
callbackUrl = 'https://app.example.com/hook' });
end)
it('ignores a stale connecting after active and a duplicate active, sending one webhook', function()
status({ conference = 'r'; agentId = 'agent-support'; state = 'connecting' });
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'connecting' }).status_code);
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'active' }).status_code);
assert.are.equal('active', mock_room.jitsiMetadata.agents['agent-support'].state);
assert.are.equal(1, #webhook_payloads('agent.connected'));
end)
it('still accepts failed after active', function()
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'media leg lost' });
assert.are.equal('failed', mock_room.jitsiMetadata.agents['agent-support'].state);
assert.are.equal(1, #webhook_payloads('agent.failed'));
end)
it('removes a failed agent on ended, with agent.failed as its only terminal webhook', function()
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'dial refused' });
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'ended' }).status_code);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support']);
assert.is_nil(mock_room._data.voice_agents['agent-support']);
assert.are.equal(1, #webhook_payloads('agent.failed'));
assert.are.equal(0, #webhook_payloads('agent.ended'));
end)
it('lets a failed agent stop counting toward the room cap once ended', function()
for i = 1, 4 do
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'extra' .. i });
status({ conference = 'r'; agentId = 'agent-extra' .. i; state = 'failed'; reason = 'x' });
status({ conference = 'r'; agentId = 'agent-extra' .. i; state = 'ended' });
end
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'fits' }).status_code);
end)
it('answers a repeated ended with 404, sending agent.ended once', function()
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'ended' }).status_code);
assert.are.equal(404, status({ conference = 'r'; agentId = 'agent-support'; state = 'ended' }).status_code);
assert.are.equal(1, #webhook_payloads('agent.ended'));
end)
it('sends no agent.ended for a failed agent when the room is destroyed', function()
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'dial refused' });
host_hooks['muc-room-destroyed']({ room = mock_room });
assert.are.equal(0, #webhook_payloads('agent.ended'));
end)
it('sends no second terminal webhook when a failed agent is dismissed', function()
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'dial refused' });
assert.are.equal(200, dismiss({ conference = 'r'; agentId = 'agent-support' }).status_code);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support']);
assert.are.equal(1, #webhook_payloads('agent.failed'));
assert.are.equal(0, #webhook_payloads('agent.ended'));
end)
end)
describe('re-invite after failure', function()
it('replaces a failed agent instead of treating it as a duplicate', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
callbackUrl = 'https://app.example.com/hook' });
status({ conference = 'r'; agentId = 'agent-support'; state = 'failed'; reason = 'no bridge' });
metadata_events = 0;
local res = invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support';
callbackUrl = 'https://app.example.com/hook' });
assert.are.equal(200, res.status_code);
assert.are.equal('provisioning', mock_room.jitsiMetadata.agents['agent-support'].state);
assert.are.equal(2, metadata_events, 'removal broadcast, then the fresh entry');
assert.are.equal(0, #webhook_payloads('agent.ended'));
end)
end)
describe('dismiss', function()
it('removes an existing agent from both the client and jicofo maps', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local res = dismiss({ conference = 'r'; agentId = 'agent-support' });
assert.are.equal(200, res.status_code);
assert.is_nil(mock_room.jitsiMetadata.agents['agent-support']);
assert.is_nil(mock_room._data.voice_agents['agent-support']);
assert.are.equal('agent-support', encoded[#encoded].agentId, '200 body echoes the agentId');
end)
it('returns 404 for an unknown agent', function()
assert.are.equal(404, dismiss({ conference = 'r'; agentId = 'agent-nope' }).status_code);
end)
end)
describe('callbackUrl host allowlist and signing', function()
it('refuses a host outside voice_agent_callback_allowed_hosts', function()
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B'; callbackUrl = 'https://evil.example.net/hook' }).status_code);
assert.are.equal(400,
invite({ conference = 'r'; displayName = 'B'; callbackUrl = 'https://app.example.com.evil.net/hook' }).status_code);
end)
it('accepts the listed host and its subdomains', function()
assert.are.equal(200, invite({ conference = 'r'; displayName = 'B'; agentId = 'one';
callbackUrl = 'https://app.example.com/hook' }).status_code);
assert.are.equal(200, invite({ conference = 'r'; displayName = 'B'; agentId = 'two';
callbackUrl = 'https://eu.app.example.com:8443/hook' }).status_code);
end)
it('logs only the host when a delivery gives up, never the URL\'s query string', function()
http_next_code = 500;
invite({ conference = 'r'; displayName = 'B'; agentId = 'support'; callbackUrl = CALLBACK .. '?token=sekrit' });
dismiss({ conference = 'r'; agentId = 'agent-support' });
while #timers > 0 do
local t = table.remove(timers, 1);
t.fn();
end
local gave_up = false;
for _, entry in ipairs(logs) do
assert.is_nil(entry.text:find('sekrit', 1, true), 'token leaked into a log line: ' .. entry.text);
if entry.text:find('app.example.com', 1, true) and entry.text:find('failed after', 1, true) then
gave_up = true;
end
end
assert.is_true(gave_up, 'expected a give-up warning naming the host');
end)
end)
describe('displayName', function()
it('rejects control characters, since it is broadcast to every client', function()
assert.are.equal(400, invite({ conference = 'r'; displayName = 'Bot\r\nX' }).status_code);
assert.are.equal(400, invite({ conference = 'r'; displayName = 'Bot\0' }).status_code);
end)
end)
describe('agentId normalization on every route', function()
it('accepts a bare id on get, status, dial and dismiss, answering with the stored id', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support'; callbackUrl = CALLBACK });
assert.are.equal(200, get('conference=r&agentId=support').status_code);
assert.are.equal('agent-support', encoded[#encoded].agentId);
assert.are.equal(200, status({ conference = 'r'; agentId = 'support'; state = 'active' }).status_code);
assert.are.equal('agent-support', encoded[#encoded].agentId);
assert.are.equal(200, dial('conference=r&agentId=support', { token = 'Bearer relay-secret' }).status_code);
assert.are.equal('agent-support', encoded[#encoded].agentId);
assert.are.equal(200, dismiss({ conference = 'r'; agentId = 'support' }).status_code);
assert.are.equal('agent-support', encoded[#encoded].agentId);
assert.are.equal(0, #agent_ids(mock_room));
end)
end)
describe('breakout rooms', function()
it('fires agent.ended when a breakout room is destroyed', function()
invite({ conference = 'r'; displayName = 'B'; agentId = 'support'; callbackUrl = CALLBACK });
local hook = host_hooks_by_host['breakout.localhost']['muc-room-destroyed'];
assert.is_function(hook, 'the destroy hook must be installed on the breakout host too');
hook({ room = mock_room });
assert.are.equal(1, #webhook_payloads('agent.ended'));
end)
end)
describe('token room scope', function()
-- token/util's verify_room gets the token's session and the resolved room; the stub answers as the test says.
it('checks the token against the resolved room JID on the provisioning routes', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
assert.are.equal(mock_room.jid, verify_room_calls[1].room);
assert.are.equal('*', verify_room_calls[1].token_room);
get('conference=r&agentId=agent-support');
assert.are.equal(2, #verify_room_calls);
end)
it('refuses a token for another room with 403 on every route, changing nothing', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
verify_room_ok = false;
assert.are.equal(403, invite({ conference = 'r'; displayName = 'Bot'; agentId = 'other' }).status_code);
assert.are.equal(403, get('conference=r&agentId=agent-support').status_code);
assert.are.equal(403, list('conference=r').status_code);
assert.are.equal(403, dismiss({ conference = 'r'; agentId = 'agent-support' }).status_code);
assert.are.equal(403, status({ conference = 'r'; agentId = 'agent-support'; state = 'active' }).status_code);
assert.are.equal(403, dial('conference=r&agentId=agent-support').status_code);
assert.are.same({ 'agent-support' }, agent_ids(mock_room));
assert.are.equal('provisioning', mock_room.jitsiMetadata.agents['agent-support'].state);
end)
it('does not scope the shared-secret callers: jicofo and the relay act on any room', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
verify_room_ok = false;
assert.are.equal(200, dial('conference=r&agentId=agent-support', { token = 'Bearer relay-secret' }).status_code);
assert.are.equal(200, status({ conference = 'r'; agentId = 'agent-support'; state = 'active' },
{ token = 'Bearer jicofo-secret' }).status_code);
end)
it('requires a room claim whatever asap_require_room_claim says', function()
assert.is_true(#require_room_claim_calls > 0);
assert.is_true(require_room_claim_calls[#require_room_claim_calls]);
end)
it('checks a breakout room as its main room', function()
breakout_room = fresh_room();
breakout_room.jid = '[email protected]';
mock_room._data.breakout_rooms_active = true;
mock_room._data.breakout_rooms = { ['[email protected]'] = true };
assert.are.equal(200, list('[email protected]').status_code);
assert.are.equal(mock_room.jid, verify_room_calls[1].room);
end)
it('refuses a breakout room whose main room cannot be found', function()
breakout_room = fresh_room();
breakout_room.jid = '[email protected]';
assert.are.equal(403, list('[email protected]').status_code);
assert.are.equal(0, #verify_room_calls);
end)
it('gives verify_room the room tenant, which it checks a context.tenant claim against', function()
token_tenant = 'acme';
list('conference=r');
assert.are.equal('', verify_room_calls[1].prefix);
mock_room.jid = '[acme][email protected]';
list('conference=r');
assert.are.equal('acme', verify_room_calls[2].prefix);
end)
it('event stream: a room that exists is checked like the routes', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
verify_room_ok = false;
local result, response = events('conference=r');
assert.are.equal(403, result.status_code);
assert.are.equal(0, #response.writes);
end)
it('event stream: a token scoped to a room that exists opens it', function()
token_room = 'r';
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local result, response = events('conference=r');
assert.is_true(result);
assert.are.equal('snapshot', stream_events(response)[1].event);
end)
it('event stream for every room opens for a scoped token and carries only the rooms it may act on', function()
token_room = 'other';
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
verify_room_ok = false;
local result, denied = events(nil);
assert.is_true(result);
verify_room_ok = true;
local _, allowed = events(nil);
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
local seen = {};
for _, e in ipairs(stream_events(denied)) do if e.event then table.insert(seen, e.event); end end
assert.are.same({ 'snapshot' }, seen, 'nothing of a room outside the token scope');
assert.are.equal('agent.connected', stream_events(allowed)[2].event);
end)
it('event stream for a room that does not exist yet opens for a scoped token', function()
token_room = 'r';
token_sub = 'acme';
assert.is_true((events('conference=acme/missing')));
end)
it('replays a missed event of a room that is gone when the token was checked against it before', function()
token_room = 'r';
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, first = events('conference=r');
local snapshot_id = stream_events(first)[1].id;
first:disconnect();
dismiss({ conference = 'r'; agentId = 'agent-support' });
gone_rooms[mock_room.jid] = true;
local _, second = events(nil, { lastEventId = snapshot_id });
local received = stream_events(second);
assert.are.equal(1, #received);
assert.are.equal('agent.ended', received[1].event);
end)
it('skips a missed event of a gone room a token was never checked against, without a snapshot', function()
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, first = events('conference=r');
local snapshot_id = stream_events(first)[1].id;
first:disconnect();
dismiss({ conference = 'r'; agentId = 'agent-support' });
gone_rooms[mock_room.jid] = true;
local _, other = events(nil, { lastEventId = snapshot_id; token = 'Bearer another' });
assert.are.equal(0, #stream_events(other), 'neither the event nor a snapshot');
end)
it('replays a missed event of a room that still exists after checking it', function()
token_room = 'r';
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
local _, first = events('conference=r');
local snapshot_id = stream_events(first)[1].id;
first:disconnect();
status({ conference = 'r'; agentId = 'agent-support'; state = 'active' });
verify_room_ok = false;
local _, denied = events(nil, { lastEventId = snapshot_id; token = 'Bearer another' });
assert.are.equal(0, #stream_events(denied));
verify_room_ok = true;
local _, allowed = events(nil, { lastEventId = snapshot_id; token = 'Bearer third' });
assert.are.equal('agent.connected', stream_events(allowed)[1].event);
end)
end)
describe('alternate configurations (module reloaded)', function()
-- Reloads the module with option overrides into the same `routes` table, so the request helpers above
-- drive the reloaded module; the defaults are restored afterwards.
local function reload_with(overrides)
option_overrides = overrides;
for k in pairs(routes) do routes[k] = nil; end
for k in pairs(shared_store) do shared_store[k] = nil; end
logs = {};
assert(pcall(dofile, 'mod_voice_agent_component.lua'));
end
after_each(function()
reload_with({});
end)
it('shares streams across the hosts the module is loaded on: a destroy seen by another instance reaches them', function()
reload_with({});
local first = {};
for k, v in pairs(routes) do first[k] = v; end
-- A second instance (the module loaded on another host) shares the store and now owns host_hooks.
assert(pcall(dofile, 'mod_voice_agent_component.lua'));
local response = sse_response();
table.insert(open_streams, response);
assert.is_true(first['GET voice-agent/events']({
request = { headers = { authorization = 'Bearer t' }; url = { query = 'conference=r' } }; response = response }));
next_decoded = { conference = 'r'; displayName = 'Bot'; agentId = 'support'; endpoint = DEFAULT_ENDPOINT };
assert.are.equal(200, first['POST voice-agent/invite']({
request = { headers = { content_type = 'application/json'; authorization = 'Bearer t' }; body = 'x' } }).status_code);
host_hooks['muc-room-destroyed']({ room = mock_room });
local received = stream_events(response);
assert.are.equal('agent.ended', received[#received].event);
local ended = webhook_payloads('agent.ended');
assert.are.equal(1, #ended, 'the destroy ends the agent once across instances');
assert.are.equal('room-destroyed', ended[1].reason);
end)
it('refuses event streams beyond voice_agent_max_event_streams with 503', function()
reload_with({ voice_agent_max_event_streams = 1 });
assert.is_true((events('conference=r')));
assert.are.equal(503, events('conference=r').status_code);
end)
it('closes a stream past voice_agent_event_stream_max_age on the keepalive tick', function()
reload_with({ voice_agent_event_stream_max_age = 0 });
local _, response = events('conference=r');
timers[#timers].fn();
assert.is_true(response.finished);
assert.are.equal('0\r\n\r\n', response.writes[#response.writes]);
end)
it('refuses to load without muc_mapper_domain_base, which the token room check resolves rooms with', function()
reload_with({ muc_mapper_domain_base = '' });
assert.is_nil(routes['POST voice-agent/invite']);
local logged = false;
for _, entry in ipairs(logs) do
if entry.level == 'error' and entry.text:find('muc_mapper_domain_base', 1, true) then logged = true; end
end
assert.is_true(logged, 'the missing option must be logged');
end)
it('refuses to load without an ASAP key repository, so a meeting token can never provision agents', function()
reload_with({ prosody_password_public_key_repo_url = '' });
assert.is_nil(next(routes), 'no route may be registered');
local said_why = false;
for _, entry in ipairs(logs) do
if entry.level == 'error' and entry.text:find('prosody_password_public_key_repo_url', 1, true) then
said_why = true;
end
end
assert.is_true(said_why);
end)
it('a dev rig without auth replays every missed event, rooms gone or not', function()
reload_with({ prosody_password_public_key_repo_url = ''; voice_agent_insecure_skip_auth = true });
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' }, { omitAuth = true });
local _, first = events('conference=r', { omitAuth = true });
local snapshot_id = stream_events(first)[1].id;
first:disconnect();
post('POST voice-agent/dismiss', { conference = 'r'; agentId = 'agent-support' }, { omitAuth = true });
gone_rooms[mock_room.jid] = true;
local _, second = events(nil, { omitAuth = true; lastEventId = snapshot_id });
assert.are.equal('agent.ended', stream_events(second)[1].event);
end)
it('loads without a key repository only under the insecure dev flag', function()
reload_with({ prosody_password_public_key_repo_url = ''; voice_agent_insecure_skip_auth = true });
assert.is_function(routes['POST voice-agent/invite']);
assert.are.equal(200, invite({ conference = 'r'; displayName = 'Bot' }, { omitAuth = true }).status_code);
end)
it('refuses a callbackUrl while webhooks cannot be signed', function()
reload_with({ voice_agent_webhook_secret = '' });
assert.are.equal(400, invite({ conference = 'r'; displayName = 'B'; callbackUrl = CALLBACK }).status_code);
assert.are.equal(200, invite({ conference = 'r'; displayName = 'B' }).status_code);
end)
it('lets the status secret read dial configs only while no dial secret is set', function()
reload_with({ voice_agent_dial_secret = '' });
invite({ conference = 'r'; displayName = 'Bot'; agentId = 'support' });
token_valid = false;
assert.are.equal(200, dial('conference=r&agentId=agent-support', { token = 'Bearer jicofo-secret' }).status_code);
end)
end)
end)