@ouro.bot/cli 0.1.0-alpha.880 → 0.1.0-alpha.881

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.881",
+      "changes": [
+        "Voice calls are authenticated end to end: the signed Twilio webhook records who is calling and hands the Media Stream (or the OpenAI SIP leg) a short-lived single-use token, and a stream or SIP call without a valid token is refused, so the caller identity, friend, direction and greeting come from server state and never from stream parameters. defaultFriendId no longer decides who an inbound caller is on any transport, friend ids are validated before they touch the friend store, the voice transport stays off without voice.twilioAuthToken, a call that cannot connect now hears a short failure line instead of dead air, and a failed transcript save or stray rejection no longer takes the voice process down. A malformed frame from an unauthenticated client no longer crashes the voice process, a second stream for the same call is refused even while the first is still starting, and a burst of more than five uncaught exceptions in a minute makes the voice process exit so its supervisor restarts it."
+      ]
+    },
     {
       "version": "0.1.0-alpha.880",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.880",
+  "runtimeVersion": "0.1.0-alpha.881",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.880</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.881</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/senses/voice/call-auth.js

@@ -0,0 +1,248 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecentIds = exports.PendingVoiceCalls = exports.DEFAULT_PENDING_VOICE_CALL_MAX_ENTRIES = exports.DEFAULT_PENDING_VOICE_CALL_TTL_MS = exports.DEFAULT_VOICE_CALL_TOKEN_TTL_MS = void 0;
+exports.newVoiceCallNonce = newVoiceCallNonce;
+exports.mintVoiceCallToken = mintVoiceCallToken;
+exports.verifyVoiceCallToken = verifyVoiceCallToken;
+const crypto = __importStar(require("node:crypto"));
+const runtime_1 = require("../../nerves/runtime");
+exports.DEFAULT_VOICE_CALL_TOKEN_TTL_MS = 60_000;
+exports.DEFAULT_PENDING_VOICE_CALL_TTL_MS = 120_000;
+exports.DEFAULT_PENDING_VOICE_CALL_MAX_ENTRIES = 256;
+const TOKEN_KEY_DOMAIN = "ouro-voice-stream-v1";
+function newVoiceCallNonce() {
+    return crypto.randomBytes(16).toString("hex");
+}
+function signingKey(secret) {
+    return crypto.createHmac("sha256", secret).update(TOKEN_KEY_DOMAIN).digest();
+}
+function sign(secret, payload) {
+    return crypto.createHmac("sha256", signingKey(secret)).update(payload).digest("base64url");
+}
+function mintVoiceCallToken(input) {
+    const claims = {
+        v: 1,
+        p: input.purpose,
+        a: input.agentName,
+        c: input.callSid,
+        d: input.direction,
+        e: input.nowMs + (input.ttlMs ?? exports.DEFAULT_VOICE_CALL_TOKEN_TTL_MS),
+        n: input.nonce ?? newVoiceCallNonce(),
+        ...(input.outboundId ? { o: input.outboundId } : {}),
+        ...(input.from ? { f: input.from } : {}),
+        ...(input.to ? { t: input.to } : {}),
+    };
+    const payload = Buffer.from(JSON.stringify(claims)).toString("base64url");
+    return `${payload}.${sign(input.secret, payload)}`;
+}
+function parseClaims(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const claims = parsed;
+    if (claims.v !== 1
+        || (claims.p !== "stream" && claims.p !== "sip")
+        || typeof claims.a !== "string"
+        || typeof claims.c !== "string"
+        || typeof claims.d !== "string"
+        || typeof claims.e !== "number"
+        || typeof claims.n !== "string")
+        return null;
+    return claims;
+}
+function verifyVoiceCallToken(input) {
+    const token = input.token.trim();
+    if (!token)
+        return { ok: false, reason: "missing" };
+    const parts = token.split(".");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return { ok: false, reason: "malformed" };
+    const [payload, signature] = parts;
+    const expected = Buffer.from(sign(input.secret, payload));
+    const actual = Buffer.from(signature);
+    if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
+        return { ok: false, reason: "bad_signature" };
+    }
+    const claims = parseClaims(payload);
+    if (!claims)
+        return { ok: false, reason: "malformed" };
+    if (input.nowMs > claims.e)
+        return { ok: false, reason: "expired" };
+    if (claims.p !== input.purpose)
+        return { ok: false, reason: "wrong_purpose" };
+    if (claims.a !== input.agentName)
+        return { ok: false, reason: "wrong_agent" };
+    if (claims.c !== input.callSid)
+        return { ok: false, reason: "wrong_call" };
+    return {
+        ok: true,
+        nonce: claims.n,
+        direction: claims.d,
+        ...(claims.o ? { outboundId: claims.o } : {}),
+        ...(claims.f ? { from: claims.f } : {}),
+        ...(claims.t ? { to: claims.t } : {}),
+    };
+}
+/**
+ * Bounded, TTL'd, in-memory record of calls the signed webhooks have admitted, keyed by CallSid.
+ * A call can hold several nonces at once (Twilio may retry the webhook while a greeting is being
+ * prepared); the first successful consume removes the whole entry, so the call connects once.
+ */
+class PendingVoiceCalls {
+    entries = new Map();
+    connected = new Map();
+    rejected = new Map();
+    ttlMs;
+    maxEntries;
+    now;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? exports.DEFAULT_PENDING_VOICE_CALL_TTL_MS;
+        this.maxEntries = options.maxEntries ?? exports.DEFAULT_PENDING_VOICE_CALL_MAX_ENTRIES;
+        this.now = options.now ?? Date.now;
+    }
+    record(identity, nonce) {
+        const existing = this.live(identity.callSid);
+        const nonces = existing?.nonces ?? new Set();
+        nonces.add(nonce);
+        // Re-insert so the Map's insertion order is least-recently-recorded first.
+        this.entries.delete(identity.callSid);
+        this.entries.set(identity.callSid, { identity, nonces, expiresAtMs: this.now() + this.ttlMs });
+        while (this.entries.size > this.maxEntries) {
+            const evicted = this.entries.keys().next().value;
+            this.entries.delete(evicted);
+            // An evicted call's stream will be refused, so make the pressure visible.
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.voice_pending_call_evicted",
+                message: "evicted a pending voice call before its stream started",
+                meta: { callSid: evicted, maxEntries: this.maxEntries },
+            });
+        }
+    }
+    consume(callSid, nonce) {
+        const entry = this.live(callSid);
+        if (!entry || !entry.nonces.has(nonce))
+            return null;
+        this.entries.delete(callSid);
+        this.remember(this.connected, callSid);
+        return entry.identity;
+    }
+    /**
+     * Remember that a stream for this call was refused, so the call's end can say so. Ignored for a
+     * call that already connected: a replayed token must not turn a good call into a failure.
+     */
+    markRejected(callSid) {
+        if (this.recalls(this.connected, callSid))
+            return;
+        this.remember(this.rejected, callSid);
+    }
+    /**
+     * Called when the stream's `<Connect>` ends. Returns true when the call never connected to a
+     * session (still waiting, or its stream was refused); forgets everything known about the call.
+     */
+    settle(callSid) {
+        const failed = this.live(callSid) !== undefined || this.recalls(this.rejected, callSid);
+        this.entries.delete(callSid);
+        this.connected.delete(callSid);
+        this.rejected.delete(callSid);
+        return failed;
+    }
+    has(callSid) {
+        return this.live(callSid) !== undefined;
+    }
+    discard(callSid) {
+        return this.entries.delete(callSid);
+    }
+    size() {
+        return this.entries.size;
+    }
+    remember(marks, callSid) {
+        marks.delete(callSid);
+        marks.set(callSid, this.now() + this.ttlMs);
+        while (marks.size > this.maxEntries)
+            marks.delete(marks.keys().next().value);
+    }
+    recalls(marks, callSid) {
+        const expiresAtMs = marks.get(callSid);
+        if (expiresAtMs === undefined)
+            return false;
+        if (this.now() > expiresAtMs) {
+            marks.delete(callSid);
+            return false;
+        }
+        return true;
+    }
+    live(callSid) {
+        const entry = this.entries.get(callSid);
+        if (!entry)
+            return undefined;
+        if (this.now() > entry.expiresAtMs) {
+            this.entries.delete(callSid);
+            return undefined;
+        }
+        return entry;
+    }
+}
+exports.PendingVoiceCalls = PendingVoiceCalls;
+/** Bounded, TTL'd "have I seen this id" set, used to ignore replayed or duplicate webhooks. */
+class RecentIds {
+    options;
+    seen = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Returns true when the id is new (and remembers it), false when it was already seen. */
+    add(id) {
+        const now = (this.options.now ?? Date.now)();
+        const expiresAtMs = this.seen.get(id);
+        if (expiresAtMs !== undefined && now <= expiresAtMs)
+            return false;
+        this.seen.delete(id);
+        this.seen.set(id, now + (this.options.ttlMs ?? 600_000));
+        while (this.seen.size > (this.options.maxEntries ?? 1_024)) {
+            this.seen.delete(this.seen.keys().next().value);
+        }
+        return true;
+    }
+}
+exports.RecentIds = RecentIds;

package/dist/senses/voice/process-guards.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installVoiceProcessGuards = installVoiceProcessGuards;
+const runtime_1 = require("../../nerves/runtime");
+function describeError(error) {
+    return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+/**
+ * Keep one bad call from taking the voice process down for every other caller. A failure that
+ * escapes a call's own handlers is logged and the process keeps serving. A burst of uncaught
+ * exceptions means the process is no longer healthy, so it exits and lets the supervisor restart it.
+ */
+function installVoiceProcessGuards(proc, options = {}) {
+    const limit = options.limit ?? 5;
+    const windowMs = options.windowMs ?? 60_000;
+    const exit = options.exit ?? ((code) => proc.exit(code));
+    const now = options.now ?? Date.now;
+    const recent = [];
+    proc.on("unhandledRejection", (reason) => {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.voice_process_error",
+            message: "Voice process caught an unhandled promise rejection and kept running",
+            meta: { kind: "unhandledRejection", error: describeError(reason) },
+        });
+    });
+    proc.on("uncaughtException", (error) => {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.voice_process_error",
+            message: "Voice process caught an uncaught exception and kept running",
+            meta: { kind: "uncaughtException", error: describeError(error) },
+        });
+        const at = now();
+        recent.push(at);
+        while (recent.length > 0 && at - recent[0] > windowMs)
+            recent.shift();
+        if (recent.length > limit) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.voice_process_crash_budget_exhausted",
+                message: "Voice process exceeded its uncaught exception budget and is exiting for a supervisor restart",
+                meta: { limit, windowMs, count: recent.length },
+            });
+            exit(1);
+        }
+    });
+}

package/dist/senses/voice/twilio-phone-runtime.js

@@ -516,6 +516,19 @@ async function startConfiguredTwilioPhoneTransport(options, deps = defaultTwilio
         });
         return { status: "disabled", reason };
     }
+    if (!settings.twilioAuthToken?.trim()) {
+        // Call tokens and webhook signatures are keyed by the Twilio auth token; without it the bridge
+        // could not tell a real Twilio call from a forged one, so it does not listen at all.
+        const reason = "voice.twilioAuthToken is required for inbound calls";
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_twilio_transport_disabled",
+            message: "Twilio phone voice transport is not attached because the Twilio auth token is missing",
+            meta: { agentName: options.agentName, reason },
+        });
+        return { status: "disabled", reason };
+    }
     await deps.cacheSelectedProviderCredentials(options.agentName);
     if (settings.openaiRealtime?.apiKeySource === "integrations.openaiEmbeddingsApiKey") {
         (0, runtime_1.emitNervesEvent)({