conductor-remote 1.99.0 → 1.101.0

package/dist-node/src/voice/gateway.js

@@ -0,0 +1,86 @@
+/** Signature-gated Twilio and OpenAI route handlers for the public voice listener. */
+import crypto from 'node:crypto';
+import { callerAllowed, mintMarker, parseForm, twimlDialSip, twimlGatherPin, twimlReject, verifyMarker, verifyTwilioSignature } from "./twiml.js";
+import { parseIncomingCall, ReplayGuard, sipHeader, verifyWebhookSignature } from "./webhook.js";
+function header(headers, name) {
+    const raw = headers[name.toLowerCase()];
+    return Array.isArray(raw) ? (raw[0] ?? null) : typeof raw === 'string' ? raw : null;
+}
+function fixedEqual(left, right) {
+    const a = crypto.createHash('sha256').update(left).digest();
+    const b = crypto.createHash('sha256').update(right).digest();
+    return crypto.timingSafeEqual(a, b);
+}
+const xml = (status, body) => ({ status, body, contentType: 'text/xml; charset=utf-8' });
+export function createVoiceGateway(deps) {
+    const replay = deps.replay ?? new ReplayGuard();
+    const now = deps.now ?? Date.now;
+    const log = deps.log ?? console.warn;
+    return {
+        async twiml(body, headers) {
+            const config = deps.config();
+            if (!config.twilioAuthToken || !config.publicBaseUrl)
+                return xml(503, twimlReject());
+            const params = parseForm(body);
+            const publicUrl = `${config.publicBaseUrl}/twiml`;
+            const signature = verifyTwilioSignature(publicUrl, params, config.twilioAuthToken, header(headers, 'x-twilio-signature'));
+            if (!signature.ok || !callerAllowed(params.From, config.allowedCallers)) {
+                log(`[voice] Twilio call refused: ${signature.ok ? 'caller not allowlisted' : signature.reason}`);
+                return xml(403, twimlReject());
+            }
+            if (!config.pin || !config.projectId)
+                return xml(503, twimlReject());
+            if (!params.Digits)
+                return xml(200, twimlGatherPin(publicUrl, config.pin.length));
+            if (!fixedEqual(params.Digits, config.pin))
+                return xml(403, twimlReject());
+            return xml(200, twimlDialSip(config.projectId, mintMarker(config.trunkSecret, now()), config.sipHost));
+        },
+        async webhook(body, headers) {
+            const config = deps.config();
+            if (!config.webhookSecret || !config.openaiKey)
+                return { status: 503, body: 'voice is not configured' };
+            const signature = verifyWebhookSignature(body, headers, config.webhookSecret, now());
+            if (!signature.ok) {
+                log(`[voice] OpenAI webhook refused: ${signature.reason}`);
+                return { status: 400, body: 'invalid webhook' };
+            }
+            const webhookId = header(headers, 'webhook-id');
+            if (!webhookId || !replay.accept(webhookId, now()))
+                return { status: 409, body: 'duplicate webhook' };
+            const call = parseIncomingCall(body);
+            if (!call)
+                return { status: 400, body: 'unexpected event' };
+            const broker = deps.broker();
+            if (!broker)
+                return { status: 503, body: 'voice broker is not configured' };
+            const marker = verifyMarker(sipHeader(call.sipHeaders, 'x-relay-call'), config.trunkSecret, now());
+            try {
+                if (!marker.ok) {
+                    log(`[voice] ${call.callId} rejected: ${marker.reason}`);
+                    await broker.reject(call.callId);
+                    return { status: 200, body: 'rejected' };
+                }
+                await broker.accept(call.callId);
+                return { status: 200, body: 'accepted' };
+            }
+            catch (error) {
+                // A non-2xx webhook response asks OpenAI to retry. Do not let our replay guard
+                // turn that legitimate retry into a duplicate after the API call failed.
+                replay.forget(webhookId);
+                throw error;
+            }
+        },
+        async rpc(message, headers) {
+            const callId = header(headers, 'x-voice-call-id');
+            if (!callId) {
+                const candidate = message;
+                const id = typeof candidate?.id === 'string' || typeof candidate?.id === 'number' || candidate?.id === null
+                    ? candidate.id
+                    : null;
+                return { jsonrpc: '2.0', id, error: { code: -32600, message: 'missing voice call id' } };
+            }
+            return deps.rpc(callId, message);
+        }
+    };
+}

package/dist-node/src/voice/preview.js

@@ -0,0 +1,67 @@
+/** Persisted, exact-text, one-use authorization for a voice dispatch. */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+export const PREVIEW_TTL_MS = 2 * 60 * 1000;
+export class PreviewStore {
+    file;
+    now;
+    previews = null;
+    constructor(file, deps = {}) {
+        this.file = file;
+        this.now = deps.now ?? Date.now;
+    }
+    read() {
+        if (this.previews)
+            return this.previews;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+            this.previews = Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            this.previews = [];
+        }
+        return this.previews;
+    }
+    write() {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        fs.writeFileSync(this.file, `${JSON.stringify(this.read(), null, 2)}\n`, { mode: 0o600 });
+        fs.chmodSync(this.file, 0o600);
+    }
+    create(input) {
+        const createdAt = this.now();
+        const preview = {
+            ...input,
+            token: crypto.randomBytes(18).toString('base64url'),
+            createdAt,
+            expiresAt: createdAt + PREVIEW_TTL_MS,
+            status: 'ready'
+        };
+        // Keep enough history to return an explicit `expired` refusal until the next
+        // preview, then bound this append-only credential file as calls accumulate.
+        this.previews = this.read().filter(candidate => candidate.expiresAt >= createdAt);
+        this.previews.push(preview);
+        this.write();
+        return preview;
+    }
+    claim(token, input) {
+        const preview = this.read().find(candidate => candidate.token === token);
+        if (!preview)
+            return { ok: false, reason: 'unknown' };
+        if (this.now() > preview.expiresAt)
+            return { ok: false, reason: 'expired' };
+        if (preview.status !== 'ready')
+            return { ok: false, reason: 'already-used' };
+        if (preview.callId !== input.callId)
+            return { ok: false, reason: 'foreign-call' };
+        if (preview.sessionId !== input.sessionId)
+            return { ok: false, reason: 'foreign-session' };
+        if (preview.text !== input.text)
+            return { ok: false, reason: 'text-mismatch' };
+        // Persist the claim before any caller starts an async UI delivery. A crash can lose a
+        // send, but cannot replay one whose outcome became unknowable.
+        preview.status = 'claimed';
+        this.write();
+        return { ok: true, preview: { ...preview } };
+    }
+}

package/dist-node/src/voice/prompt.js

@@ -0,0 +1,12 @@
+/** Snapshot-worthy instructions: the model presents relay-owned facts and routes choices. */
+export const VOICE_INSTRUCTIONS = `You are a voice switchboard for the user's Conductor agents. You do not solve engineering work and you do not invent fleet state.
+
+Start with voice_roll_call. Work through one decision at a time with voice_next_decision. Speak only the tool result's spoken field; never read ids, cursors, JSON keys, or tokens aloud. Keep replies short enough for someone walking.
+
+Every time the user asks for a workspace overview, status, progress, or what is happening across the fleet, call voice_workspace_overview starting at cursor zero. This is a fresh read, so never answer that request from the opening roll call or an earlier overview. If they ask to continue, pass the cursor returned by the prior overview.
+
+When the user wants to dispatch text, call voice_send_preview with the exact target and text. Read the exact preview back, including the target, and ask for an explicit yes. Only after yes, call voice_send with the returned token and exactly the same session and text. Never call voice_send without that confirmation. A send queues asynchronously; success is silent, while parked or failed delivery will be announced.
+
+After a dispatch, or when the user explicitly says to skip, mark that decision handled and continue only when they ask for next. If a target is working, explain that sending would steer the running turn and do not send; this first tool set only dispatches to idle chats.
+
+Use the safe options the relay supplies. If asked to reason deeply, forward a concise question to the workspace that owns the context rather than answering it yourself. If a tool refuses an action, say its sentence plainly and do not work around the gate.`;

package/dist-node/src/voice/server.js

@@ -0,0 +1,137 @@
+/**
+ * The voice listener: a second HTTP server on its own loopback port, carrying only what
+ * OpenAI's and Twilio's servers must be able to reach.
+ *
+ * Why it is not part of `src/server.ts` (design ▸ D2). Those two callers need a public
+ * address, and Tailscale's Funnel flag is per host:port — so anything sharing the relay's
+ * port would go public with it. A separate port keeps the relay tailnet-only while exactly
+ * three routes face the internet. It also means a bug in this file cannot answer `/api/…`.
+ *
+ * **Public path vs local path.** Funnel mounts this at `--set-path=/voice` on 443, and
+ * Tailscale *strips* the mount prefix before proxying, so the public
+ * `https://<node>/voice/webhook` arrives here as `/webhook` (measured 2026-09-02). A direct
+ * loopback curl uses the local path, and a future mount at `/` would not strip. Both spellings
+ * are accepted, because the alternative is a 404 whose cause is invisible from either side.
+ *
+ * **Why 443 and not 8443** (probe 0a, same day): OpenAI's cloud connects to port 443 and to
+ * nothing else. Funnel's other ports answer an ordinary browser and are never dialled.
+ *
+ * Nothing here verifies a signature or speaks JSON-RPC. The routes are injected, so the caller
+ * gate (`twiml.ts`, `webhook.ts`) and the tool set (`tools.ts`) are written and tested apart
+ * from the plumbing, and this file stays the one place the HTTP rules live.
+ */
+import crypto from 'node:crypto';
+import http from 'node:http';
+/** A body big enough for any webhook and small enough that a token holder cannot exhaust memory. */
+export const MAX_BODY_BYTES = 1_000_000;
+/** Constant-time compare that does not leak the length of the expected token either. */
+function tokenEq(given, expected) {
+    if (!given)
+        return false;
+    const a = crypto.createHash('sha256').update(given).digest();
+    const b = crypto.createHash('sha256').update(expected).digest();
+    return crypto.timingSafeEqual(a, b);
+}
+function bearer(req) {
+    const auth = req.headers.authorization;
+    return auth?.startsWith('Bearer ') ? auth.slice('Bearer '.length) : null;
+}
+/**
+ * The local route name for a request path. Tailscale strips the `/voice` mount prefix, so both
+ * spellings map to the same route; anything else is null and gets a 404.
+ */
+export function routeName(pathname) {
+    const trimmed = pathname.replace(/\/+$/, '') || '/';
+    // The OpenAI dashboard is already configured to the mount itself (`…/voice`). Funnel
+    // strips that mount and the listener sees `/`; a direct loopback check sees `/voice`.
+    if (trimmed === '/' || trimmed === '/voice')
+        return 'webhook';
+    const local = trimmed.startsWith('/voice/') ? trimmed.slice('/voice'.length) : trimmed;
+    if (local === '/webhook')
+        return 'webhook';
+    if (local === '/twiml')
+        return 'twiml';
+    if (local === '/mcp')
+        return 'mcp';
+    return null;
+}
+async function readBody(req) {
+    const declared = Number(req.headers['content-length']);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES)
+        return null;
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of req) {
+        bytes += chunk.length;
+        if (bytes > MAX_BODY_BYTES)
+            return null;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function send(res, reply) {
+    const headers = { 'cache-control': 'no-store' };
+    if (reply.body !== undefined)
+        headers['content-type'] = reply.contentType ?? 'text/plain; charset=utf-8';
+    res.writeHead(reply.status, headers).end(reply.body ?? '');
+}
+const RPC_PARSE_ERROR = JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+/**
+ * Handle one request. Exported so a test can drive it without a socket, and so the rules —
+ * which route, which method, which gate — are readable in one place rather than spread over
+ * a dispatcher.
+ */
+export async function handleVoiceRequest(deps, req, res) {
+    const pathname = new URL(req.url ?? '/', 'http://x').pathname;
+    const route = routeName(pathname);
+    // A 404 that names nothing: the routes are each behind a secret, and an attacker who finds
+    // them still gets nowhere, but there is no reason to enumerate them either.
+    if (!route)
+        return send(res, { status: 404, body: 'not found' });
+    if (req.method !== 'POST') {
+        return send(res, { status: 405, body: 'POST only', contentType: 'text/plain; charset=utf-8' });
+    }
+    if (route === 'mcp') {
+        // A real MCP client sends no Origin and a browser cannot omit one, so this single check
+        // closes the DNS-rebinding hole without the listener needing to know its own hostname.
+        if (req.headers.origin)
+            return send(res, { status: 403, body: 'cross-origin requests are not accepted here' });
+        if (!tokenEq(bearer(req), deps.mcpToken()))
+            return send(res, { status: 401, body: 'unauthorized' });
+    }
+    const body = await readBody(req);
+    if (body === null)
+        return send(res, { status: 413, body: 'request too large' });
+    if (route === 'webhook')
+        return send(res, await deps.routes.webhook(body, req.headers));
+    if (route === 'twiml')
+        return send(res, await deps.routes.twiml(body, req.headers));
+    let parsed;
+    try {
+        parsed = JSON.parse(body || 'null');
+    }
+    catch {
+        return send(res, { status: 400, body: RPC_PARSE_ERROR, contentType: 'application/json' });
+    }
+    const batch = Array.isArray(parsed) ? parsed : [parsed];
+    const settled = await Promise.all(batch.map(m => deps.routes.rpc(m, req.headers)));
+    const answers = settled.filter(a => a !== null);
+    // A payload of nothing but notifications takes no reply at all.
+    if (!answers.length)
+        return send(res, { status: 202 });
+    send(res, {
+        status: 200,
+        body: JSON.stringify(Array.isArray(parsed) ? answers : answers[0]),
+        contentType: 'application/json'
+    });
+}
+/** Bound to loopback only: everything public arrives through Tailscale, never off the LAN. */
+export function createVoiceServer(deps) {
+    return http.createServer((req, res) => {
+        handleVoiceRequest(deps, req, res).catch(err => {
+            deps.log?.(`[voice] request failed: ${err instanceof Error ? err.message : err}`);
+            if (!res.headersSent)
+                send(res, { status: 500, body: 'internal error' });
+        });
+    });
+}

package/dist-node/src/voice/ticket.js

@@ -0,0 +1,23 @@
+import { MARKER_MAX_AGE_SECONDS, mintMarker, sipTicketUri } from "./twiml.js";
+/** Settings required before a ticket has any chance of becoming an accepted call. */
+export function missingTicketConfig(config) {
+    const missing = [];
+    if (!config.projectId)
+        missing.push('voice.project-id');
+    if (!config.openaiKey)
+        missing.push('voice.openai-key');
+    if (!config.webhookSecret)
+        missing.push('voice.webhook-secret');
+    if (!config.publicBaseUrl)
+        missing.push('voice.public-url');
+    return missing;
+}
+/** Mint only after `missingTicketConfig` is empty. The marker's nonce makes every URI fresh. */
+export function mintSipTicket(config, nowMs = Date.now()) {
+    if (!config.projectId)
+        throw new Error('voice.project-id is not configured');
+    return {
+        uri: sipTicketUri(config.projectId, mintMarker(config.trunkSecret, nowMs), config.sipHost),
+        expiresAt: new Date(nowMs + MARKER_MAX_AGE_SECONDS * 1000).toISOString()
+    };
+}

package/dist-node/src/voice/tools.js

@@ -0,0 +1,198 @@
+import { oneLine } from "../speech.js";
+/**
+ * One definition table feeds both transports: SIP exposes it through the scoped
+ * MCP server, while the PWA's private sideband exposes the same entries as
+ * Realtime function tools. Keeping the schemas here means those two callers can
+ * never quietly acquire different powers.
+ */
+export const VOICE_TOOL_NAMES = [
+    'voice_roll_call',
+    'voice_workspace_overview',
+    'voice_next_decision',
+    'voice_send_preview',
+    'voice_send'
+];
+export const VOICE_TOOL_DEFINITIONS = [
+    {
+        name: 'voice_roll_call',
+        description: 'Get the bounded fleet tally and the first queue heads. Start every call here.',
+        inputSchema: { type: 'object', properties: {} }
+    },
+    {
+        name: 'voice_workspace_overview',
+        description: 'Get a fresh overview of current workspaces with each latest agent update. Call this every time the user asks for an overview or workspace status, even if one was already given. Pass the returned cursor to continue.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cursor: { type: 'number', description: 'The cursor returned by the previous overview page; default 0.' }
+            }
+        }
+    },
+    {
+        name: 'voice_next_decision',
+        description: 'Get exactly one bounded decision. Pass the returned cursor for the next item. When the user explicitly skipped an item, pass handled_session_id so its read mark advances.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cursor: { type: 'number', description: 'The cursor returned by the previous decision; default 0.' },
+                handled_session_id: {
+                    type: 'string',
+                    description: 'A session the user explicitly skipped; merely hearing it is not handled.'
+                }
+            }
+        }
+    },
+    {
+        name: 'voice_send_preview',
+        description: 'Create a two-minute exact-text send preview. Speak its exact target and text and ask for yes before using voice_send.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string' },
+                session_id: { type: 'string' },
+                text: { type: 'string' }
+            },
+            required: ['workspace_id', 'session_id', 'text']
+        }
+    },
+    {
+        name: 'voice_send',
+        description: 'Queue an exact preview after the user said yes. Requires its token, session and unchanged text; never accepts raw unpreviewed work.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                token: { type: 'string' },
+                session_id: { type: 'string' },
+                text: { type: 'string' }
+            },
+            required: ['token', 'session_id', 'text']
+        }
+    }
+];
+/** Realtime's function-tool spelling of the same scoped definitions. */
+export function voiceFunctionTools() {
+    return VOICE_TOOL_DEFINITIONS.map(tool => ({
+        type: 'function',
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.inputSchema
+    }));
+}
+function need(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${key} is required`);
+    return value.trim();
+}
+function answer(value) {
+    return JSON.stringify(value);
+}
+function refusal(reason) {
+    switch (reason) {
+        case 'expired':
+            return 'That preview expired. Read the exact target and text back again before sending.';
+        case 'foreign-call':
+            return 'That preview belongs to another call and cannot be used here.';
+        case 'foreign-session':
+            return 'That preview belongs to a different chat. Preview this target again.';
+        case 'text-mismatch':
+            return 'The send text does not exactly match the preview. Preview the changed text first.';
+        case 'already-used':
+            return 'That preview was already used. The relay will not send it twice.';
+        case 'unknown':
+            return 'That preview token is unknown. Make a new preview before sending.';
+    }
+}
+function later(task) {
+    setImmediate(() => void task());
+}
+/** Build a fresh scoped tool set for one authenticated call. */
+export function createVoiceTools(context) {
+    const definition = (name) => {
+        const found = VOICE_TOOL_DEFINITIONS.find(tool => tool.name === name);
+        if (!found)
+            throw new Error(`missing voice tool definition ${name}`);
+        return found;
+    };
+    return [
+        {
+            ...definition('voice_roll_call'),
+            run: async () => answer(await context.board.rollCall())
+        },
+        {
+            ...definition('voice_workspace_overview'),
+            run: async (args) => {
+                const cursor = typeof args.cursor === 'number' && Number.isFinite(args.cursor) ? args.cursor : 0;
+                return answer(await context.board.workspaceOverview(cursor));
+            }
+        },
+        {
+            ...definition('voice_next_decision'),
+            run: async (args) => {
+                if (typeof args.handled_session_id === 'string')
+                    context.board.markHandled(args.handled_session_id);
+                const cursor = typeof args.cursor === 'number' && Number.isFinite(args.cursor) ? args.cursor : 0;
+                const next = await context.board.nextDecision(cursor);
+                return answer(next ?? { spoken: 'There are no more decisions in this call.', cursor, done: true });
+            }
+        },
+        {
+            ...definition('voice_send_preview'),
+            run: async (args) => {
+                const workspaceId = need(args, 'workspace_id');
+                const sessionId = need(args, 'session_id');
+                const text = need(args, 'text');
+                const session = context.findSession(sessionId);
+                if (!session || session.workspaceId !== workspaceId)
+                    return answer({ status: 'refused', spoken: 'That chat is no longer in the named workspace.' });
+                const preview = context.previews.create({ callId: context.callId, workspaceId, sessionId, text });
+                return answer({
+                    status: 'preview',
+                    token: preview.token,
+                    workspaceId,
+                    sessionId,
+                    text,
+                    spoken: `Preview for ${oneLine(session.workspaceTitle, 80)}: “${oneLine(text, 220)}” Say yes to send this exact text.`
+                });
+            }
+        },
+        {
+            ...definition('voice_send'),
+            run: async (args) => {
+                const token = need(args, 'token');
+                const sessionId = need(args, 'session_id');
+                const text = need(args, 'text');
+                const session = context.findSession(sessionId);
+                if (!session)
+                    return answer({ status: 'refused', spoken: 'That chat is no longer available. Nothing was sent.' });
+                if (session.status === 'working') {
+                    return answer({
+                        status: 'refused',
+                        spoken: `${oneLine(session.workspaceTitle, 80)} is running. Sending now would steer its active turn, so nothing was sent.`
+                    });
+                }
+                const claimed = context.previews.claim(token, { callId: context.callId, sessionId, text });
+                if (!claimed.ok)
+                    return answer({ status: 'refused', spoken: refusal(claimed.reason) });
+                if (claimed.preview.workspaceId !== session.workspaceId) {
+                    return answer({ status: 'refused', spoken: 'That chat moved to another workspace. Nothing was sent.' });
+                }
+                context.board.markHandled(sessionId);
+                later(async () => {
+                    try {
+                        const result = await context.dispatch(claimed.preview);
+                        if (result.ok)
+                            return;
+                        if (result.parked)
+                            return void (await context.announce('The prompt is parked until the Mac unlocks.'));
+                        await context.announce(`The prompt did not land. ${oneLine(result.error ?? 'Try again later.', 220)}`);
+                    }
+                    catch (error) {
+                        await context.announce(`The prompt did not land. ${oneLine(error instanceof Error ? error.message : String(error), 220)}`);
+                    }
+                });
+                return answer({ status: 'queued', spoken: `Queued for ${oneLine(session.workspaceTitle, 80)}.` });
+            }
+        }
+    ];
+}

package/dist-node/src/voice/twiml.js

@@ -0,0 +1,124 @@
+/**
+ * The Twilio side of the caller gate, and the TwiML it answers with.
+ *
+ * The number authenticates nobody — anyone who dials it reaches whatever answers (eng review's
+ * correction to P3), so three things happen before OpenAI is bridged. `X-Twilio-Signature` proves
+ * Twilio sent the request. The `From` allowlist proves it is a phone we know. The DTMF PIN proves
+ * it is a person who knows the secret rather than a stolen handset. Only then does the `<Dial>`
+ * go out, carrying a trunk marker the OpenAI webhook re-checks, so a stranger who guesses the
+ * project id and dials the SIP address directly still reaches nothing.
+ *
+ * The marker carries no phone number and no call id. It is a timestamp, a nonce and an HMAC over
+ * both, which is all the webhook needs to know the leg came from here and came recently — and it
+ * transits OpenAI's servers, so putting the caller's number in it would be leaking the one piece
+ * of PII this whole path otherwise avoids.
+ */
+import crypto from 'node:crypto';
+/** A marker older than this is refused. A Twilio bridge takes seconds; this is generous. */
+export const MARKER_MAX_AGE_SECONDS = 120;
+const bad = (reason) => ({ ok: false, reason });
+function equal(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && crypto.timingSafeEqual(left, right);
+}
+/**
+ * Twilio signs the exact URL it requested plus every POST parameter, sorted by name and
+ * concatenated as `name + value` with no separators, HMAC-SHA1 under the account's auth token.
+ * The URL must be the public one Twilio dialled, not the loopback path this process sees.
+ */
+export function twilioSignature(url, params, authToken) {
+    const payload = Object.keys(params)
+        .sort()
+        .reduce((acc, key) => acc + key + params[key], url);
+    return crypto.createHmac('sha1', authToken).update(payload).digest('base64');
+}
+export function verifyTwilioSignature(url, params, authToken, signature) {
+    if (!signature)
+        return bad('missing X-Twilio-Signature');
+    return equal(signature, twilioSignature(url, params, authToken)) ? { ok: true } : bad('X-Twilio-Signature mismatch');
+}
+/** `application/x-www-form-urlencoded`, which is what Twilio posts. Last value wins, as Twilio sends one each. */
+export function parseForm(body) {
+    const out = {};
+    for (const [key, value] of new URLSearchParams(body))
+        out[key] = value;
+    return out;
+}
+/**
+ * E.164 comparison that tolerates the spacing and punctuation a person types into a settings file.
+ * Anything that is not a digit or a leading plus is noise; two numbers match when their digits do.
+ */
+export function sameNumber(a, b) {
+    const digits = (s) => s.replace(/[^\d]/g, '');
+    return digits(a).length > 0 && digits(a) === digits(b);
+}
+export function callerAllowed(from, allowlist) {
+    return Boolean(from) && allowlist.some(entry => sameNumber(entry, from));
+}
+// ── the trunk marker ────────────────────────────────────────────────────────────────────────
+function markerMac(secret, stamp, nonce) {
+    return crypto.createHmac('sha256', secret).update(`${stamp}.${nonce}`).digest('base64url');
+}
+/** `<unix seconds>.<nonce>.<mac>` — URL- and SIP-header-safe, since base64url avoids `+/=`. */
+export function mintMarker(secret, nowMs = Date.now(), nonce) {
+    const stamp = String(Math.floor(nowMs / 1000));
+    const n = nonce ?? crypto.randomBytes(9).toString('base64url');
+    return `${stamp}.${n}.${markerMac(secret, stamp, n)}`;
+}
+export function verifyMarker(marker, secret, nowMs = Date.now(), maxAgeSeconds = MARKER_MAX_AGE_SECONDS) {
+    if (!marker)
+        return bad('no trunk marker on the call');
+    const parts = marker.split('.');
+    if (parts.length !== 3)
+        return bad('trunk marker is malformed');
+    const [stamp, nonce, mac] = parts;
+    const sent = Number(stamp);
+    if (!Number.isFinite(sent))
+        return bad('trunk marker has no timestamp');
+    const age = nowMs / 1000 - sent;
+    // A marker from the future is a clock problem or a forgery; either way it is not ours.
+    if (age < -maxAgeSeconds || age > maxAgeSeconds)
+        return bad(`trunk marker is ${Math.round(age)}s old`);
+    return equal(mac, markerMac(secret, stamp, nonce)) ? { ok: true } : bad('trunk marker does not verify');
+}
+// ── TwiML ───────────────────────────────────────────────────────────────────────────────────
+/** Everything interpolated below is either ours or a caller-controlled string, so all of it escapes. */
+export function xmlEscape(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+const doc = (inner) => `<?xml version="1.0" encoding="UTF-8"?>\n<Response>${inner}</Response>\n`;
+/** The answer to anything that fails a check. Says nothing about which check, or that it was close. */
+export function twimlReject() {
+    return doc('<Reject reason="rejected"/>');
+}
+/** Ask for the PIN. `action` is the public URL Twilio should post the digits back to. */
+export function twimlGatherPin(action, digits) {
+    return doc(`<Gather input="dtmf" numDigits="${digits}" timeout="10" action="${xmlEscape(action)}" method="POST">` +
+        '<Say>Enter your pin.</Say>' +
+        '</Gather>' +
+        '<Say>No pin entered.</Say>' +
+        '<Reject reason="rejected"/>');
+}
+/**
+ * The short-lived address used by both Twilio and the native app. Keep it in one
+ * function so neither path can accidentally normalise the case-sensitive project id
+ * or omit TLS/the relay marker.
+ */
+export function sipTicketUri(projectId, marker, host = 'sip.api.openai.com') {
+    return `sip:${projectId}@${host};transport=tls?X-Relay-Call=${marker}`;
+}
+/**
+ * Bridge to OpenAI. The project id is **case-sensitive** in the SIP user part (P3: Linphone
+ * lowercasing it is what demoted the softphone path), so it is interpolated exactly as configured
+ * and never normalised here.
+ */
+export function twimlDialSip(projectId, marker, host = 'sip.api.openai.com') {
+    const uri = sipTicketUri(projectId, marker, host);
+    return doc(`<Dial answerOnBridge="true"><Sip>${xmlEscape(uri)}</Sip></Dial>`);
+}