@fonoster/common 0.27.0 → 0.30.0

package/dist/net/assertPublicDestination.js

@@ -0,0 +1,342 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsafeDestinationError = void 0;
+exports.isPrivateAddress = isPrivateAddress;
+exports.assertPublicDestination = assertPublicDestination;
+exports.assertPublicUrlShape = assertPublicUrlShape;
+exports.publicWebSocketGuard = publicWebSocketGuard;
+exports.assertPublicWebSocketUrlShape = assertPublicWebSocketUrlShape;
+exports.safeFetch = safeFetch;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const node_dns_1 = __importDefault(require("node:dns"));
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_net_1 = __importDefault(require("node:net"));
+const node_url_1 = require("node:url");
+/* global Response, Headers */
+/**
+ * Outbound requests to tenant-chosen URLs (Autopilot HTTP tools, webhooks) must not reach the
+ * platform's own network (SSRF, RV-B2): http/https only, and every address the host resolves to
+ * must be public. Operators who self-host can allow internal destinations with
+ * `FONOSTER_ALLOWED_DESTINATIONS` (comma-separated host names, IPs or CIDRs; default empty).
+ */
+class UnsafeDestinationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsafeDestinationError";
+    }
+}
+exports.UnsafeDestinationError = UnsafeDestinationError;
+const blocked = new node_net_1.default.BlockList();
+for (const [net4, prefix] of [
+    ["0.0.0.0", 8], // "this network", 0.0.0.0
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10], // CGNAT
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16], // link-local, cloud metadata
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4] // reserved, broadcast
+])
+    blocked.addSubnet(net4, prefix, "ipv4");
+for (const [net6, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["64:ff9b::", 96], // NAT64 can reach IPv4 private ranges
+    ["100::", 64],
+    ["2001:db8::", 32],
+    ["fc00::", 7], // ULA
+    ["fe80::", 10], // link-local
+    ["ff00::", 8] // multicast
+])
+    blocked.addSubnet(net6, prefix, "ipv6");
+const INTERNAL_SUFFIXES = [
+    ".localhost",
+    ".local",
+    ".internal",
+    ".intranet",
+    ".lan",
+    ".home.arpa",
+    ".cluster.local",
+    ".svc"
+];
+/** The IPv4 address inside an IPv4-mapped IPv6 address (::ffff:a.b.c.d or ::ffff:hhhh:hhhh). */
+function mappedV4(ip) {
+    const m = /^::ffff:(.+)$/i.exec(ip);
+    if (!m)
+        return undefined;
+    if (node_net_1.default.isIPv4(m[1]))
+        return m[1];
+    const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(m[1]);
+    if (!hex)
+        return undefined;
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    return [hi >> 8, hi & 255, lo >> 8, lo & 255].join(".");
+}
+/** True when the address is loopback, private, link-local, ULA, CGNAT, multicast or reserved. */
+function isPrivateAddress(ip) {
+    const bare = ip.replace(/^\[|\]$/g, "").split("%")[0];
+    const v4 = mappedV4(bare);
+    if (v4)
+        return blocked.check(v4, "ipv4");
+    if (node_net_1.default.isIPv4(bare))
+        return blocked.check(bare, "ipv4");
+    if (node_net_1.default.isIPv6(bare))
+        return blocked.check(bare, "ipv6");
+    return true; // not an address: refuse
+}
+function allowList(policy) {
+    var _a, _b;
+    return ((_a = policy === null || policy === void 0 ? void 0 : policy.allow) !== null && _a !== void 0 ? _a : ((_b = process.env.FONOSTER_ALLOWED_DESTINATIONS) !== null && _b !== void 0 ? _b : "").split(","))
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
+function allowedByOperator(host, ip, allow) {
+    var _a;
+    for (const entry of allow) {
+        if (entry === host)
+            return true;
+        if (!ip)
+            continue;
+        const [base, bits] = entry.split("/");
+        if (!node_net_1.default.isIP(base))
+            continue;
+        const family = node_net_1.default.isIPv4(base) ? "ipv4" : "ipv6";
+        const list = new node_net_1.default.BlockList();
+        const prefix = bits ? Number(bits) : family === "ipv4" ? 32 : 128;
+        list.addSubnet(base, prefix, family);
+        const target = (_a = mappedV4(ip)) !== null && _a !== void 0 ? _a : ip;
+        const targetFamily = node_net_1.default.isIPv4(target) ? "ipv4" : "ipv6";
+        if (targetFamily === family && list.check(target, family))
+            return true;
+    }
+    return false;
+}
+function checkAddress(host, ip, allow) {
+    if (isPrivateAddress(ip) && !allowedByOperator(host, ip, allow))
+        throw new UnsafeDestinationError(`destination ${host} resolves to a non-public address`);
+}
+function hostOf(url) {
+    return url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+}
+/** Throws unless the URL is http(s) and its host is public, before any DNS lookup. */
+function checkUrlShape(url, allow) {
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new UnsafeDestinationError(`unsupported scheme ${url.protocol}`);
+    const host = hostOf(url);
+    if (!host)
+        throw new UnsafeDestinationError("missing host");
+    if (node_net_1.default.isIP(host)) {
+        checkAddress(host, host, allow);
+        return host;
+    }
+    if (allow.includes(host))
+        return host;
+    const name = host.replace(/\.$/, "");
+    if (!name.includes(".") ||
+        name === "localhost" ||
+        INTERNAL_SUFFIXES.some((s) => name.endsWith(s)))
+        throw new UnsafeDestinationError(`destination ${host} is an internal name`);
+    return host;
+}
+/**
+ * Checks a tenant-chosen URL: http/https, not an internal name, and every resolved address
+ * public (or allowed by the operator). Returns the parsed URL.
+ */
+function assertPublicDestination(input, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let url;
+        try {
+            url = new node_url_1.URL(String(input));
+        }
+        catch (_a) {
+            throw new UnsafeDestinationError("invalid URL");
+        }
+        const allow = allowList(policy);
+        const host = checkUrlShape(url, allow);
+        if (node_net_1.default.isIP(host) || allow.includes(host))
+            return url;
+        let addresses;
+        try {
+            addresses = yield node_dns_1.default.promises.lookup(host, { all: true });
+        }
+        catch (_b) {
+            throw new UnsafeDestinationError(`cannot resolve ${host}`);
+        }
+        for (const a of addresses)
+            checkAddress(host, a.address, allow);
+        return url;
+    });
+}
+/** Synchronous shape check (scheme, literal IPs, internal names) for request validation. */
+function assertPublicUrlShape(input, policy) {
+    let url;
+    try {
+        url = new node_url_1.URL(String(input));
+    }
+    catch (_a) {
+        throw new UnsafeDestinationError("invalid URL");
+    }
+    checkUrlShape(url, allowList(policy));
+    return url;
+}
+// The connection is checked when the socket resolves the name, so a DNS answer that changes
+// between the check and the request (rebinding) cannot reach a private address.
+function guardedLookup(host, allow) {
+    return (hostname, options, callback) => {
+        node_dns_1.default.lookup(hostname, Object.assign(Object.assign({}, options), { all: true }), (err, addrs) => {
+            if (err)
+                return callback(err, "", 4);
+            const list = addrs;
+            try {
+                for (const a of list)
+                    checkAddress(host, a.address, allow);
+            }
+            catch (e) {
+                return callback(e, "", 4);
+            }
+            if (options.all)
+                return callback(null, list);
+            callback(null, list[0].address, list[0].family);
+        });
+    };
+}
+/** A ws:// or wss:// URL as the http(s) URL its handshake uses. */
+function asHttpUrl(input) {
+    return String(input).replace(/^ws(s?):/i, "http$1:");
+}
+/**
+ * For WebSocket connections to tenant-chosen URLs (session apps, listeners): checks the URL's
+ * shape (ws/wss, no internal names or private literal IPs) and returns a socket `lookup` that
+ * refuses private addresses when the name resolves. Pass it as the `lookup` option of `ws`.
+ */
+function publicWebSocketGuard(input, policy) {
+    if (!/^wss?:\/\//i.test(String(input)))
+        throw new UnsafeDestinationError("unsupported scheme");
+    const allow = allowList(policy);
+    const url = assertPublicUrlShape(asHttpUrl(input), { allow });
+    return { lookup: guardedLookup(hostOf(url), allow) };
+}
+/** Synchronous shape check of a ws:// or wss:// URL (see assertPublicUrlShape). */
+function assertPublicWebSocketUrlShape(input, policy) {
+    if (!/^wss?:\/\//i.test(String(input)))
+        throw new UnsafeDestinationError("unsupported scheme");
+    return assertPublicUrlShape(asHttpUrl(input), policy);
+}
+const NO_BODY = new Set([101, 204, 205, 304]);
+function requestOnce(url, init, method, body, signal, allow) {
+    const lookup = guardedLookup(hostOf(url), allow);
+    const lib = url.protocol === "https:" ? node_https_1.default : node_http_1.default;
+    return new Promise((resolve, reject) => {
+        var _a;
+        const req = lib.request(url, {
+            method,
+            headers: Object.assign(Object.assign({}, ((_a = init.headers) !== null && _a !== void 0 ? _a : {})), (body !== undefined
+                ? { "content-length": String(Buffer.byteLength(body)) }
+                : {})),
+            lookup,
+            signal
+        }, (res) => {
+            var _a;
+            const chunks = [];
+            let size = 0;
+            const max = (_a = init.maxBytes) !== null && _a !== void 0 ? _a : 5 * 1024 * 1024;
+            res.on("data", (c) => {
+                size += c.length;
+                if (size > max) {
+                    res.destroy(new UnsafeDestinationError("response too large"));
+                    return;
+                }
+                chunks.push(c);
+            });
+            res.on("error", reject);
+            res.on("end", () => {
+                var _a;
+                const headers = new Headers();
+                for (const [k, v] of Object.entries(res.headers)) {
+                    if (v === undefined)
+                        continue;
+                    for (const item of Array.isArray(v) ? v : [v])
+                        headers.append(k, item);
+                }
+                const status = (_a = res.statusCode) !== null && _a !== void 0 ? _a : 0;
+                resolve(new Response(NO_BODY.has(status) ? null : Buffer.concat(chunks), {
+                    status: status < 200 || status > 599 ? 502 : status,
+                    statusText: res.statusMessage,
+                    headers
+                }));
+            });
+        });
+        req.on("error", reject);
+        if (body !== undefined)
+            req.write(body);
+        req.end();
+    });
+}
+/**
+ * fetch for tenant-chosen URLs: checks the destination (and each redirect) with
+ * assertPublicDestination, re-checks the addresses the socket connects to, and times out.
+ */
+function safeFetch(input_1) {
+    return __awaiter(this, arguments, void 0, function* (input, init = {}) {
+        var _a, _b, _c;
+        const allow = allowList(init.policy);
+        const timeout = AbortSignal.timeout((_a = init.timeoutMs) !== null && _a !== void 0 ? _a : 10000);
+        const signal = init.signal
+            ? AbortSignal.any([init.signal, timeout])
+            : timeout;
+        let url = yield assertPublicDestination(input, { allow });
+        let method = ((_b = init.method) !== null && _b !== void 0 ? _b : "GET").toUpperCase();
+        let body = init.body;
+        const maxRedirects = (_c = init.maxRedirects) !== null && _c !== void 0 ? _c : 3;
+        for (let hop = 0;; hop++) {
+            const res = yield requestOnce(url, init, method, body, signal, allow);
+            const location = res.headers.get("location");
+            if (![301, 302, 303, 307, 308].includes(res.status) || !location)
+                return res;
+            if (hop >= maxRedirects)
+                throw new UnsafeDestinationError("too many redirects");
+            url = yield assertPublicDestination(new node_url_1.URL(location, url), { allow });
+            if (res.status === 303 || (res.status <= 302 && method === "POST")) {
+                method = "GET";
+                body = undefined;
+            }
+        }
+    });
+}

package/dist/{voice/PlayDtmf.d.ts → net/index.d.ts}

@@ -16,8 +16,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { VerbRequest } from "./Verb";
-type PlayDtmfRequest = VerbRequest & {
-    digits: string;
-};
-export { PlayDtmfRequest };
+export * from "./assertPublicDestination";

package/dist/{voice → net}/index.js

@@ -32,16 +32,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-__exportStar(require("./Dial"), exports);
-__exportStar(require("./Gather"), exports);
-__exportStar(require("./Mute"), exports);
-__exportStar(require("./Play"), exports);
-__exportStar(require("./PlayDtmf"), exports);
-__exportStar(require("./PlaybackControl"), exports);
-__exportStar(require("./Record"), exports);
-__exportStar(require("./Say"), exports);
-__exportStar(require("./Stream"), exports);
-__exportStar(require("./StreamGather"), exports);
-__exportStar(require("./StopSay"), exports);
-__exportStar(require("./Verb"), exports);
-__exportStar(require("./voice"), exports);
+__exportStar(require("./assertPublicDestination"), exports);

package/dist/notifications/createSendEmail.js

@@ -37,7 +37,9 @@ function createSendEmail(config) {
         host,
         port,
         secure,
-        auth
+        // Relays without authentication (e.g. a local MailHog) get no auth block;
+        // an empty one makes nodemailer fail with "Missing credentials".
+        auth: (auth === null || auth === void 0 ? void 0 : auth.user) ? auth : undefined
     });
     return function sendEmail(params) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/protos/applications.proto

@@ -39,13 +39,69 @@ service Applications {
   rpc EvaluateIntelligence(EvaluateIntelligenceRequest) returns (stream EvaluateIntelligenceEvent);
   // Create an Ephemeral Agent to perform test calls to an application
   rpc CreateTestToken(google.protobuf.Empty) returns (TestTokenResponse) {}
+  // Replace an application's signing secret; the old one stops working at once (no overlap)
+  rpc RotateSigningSecret(RotateSigningSecretRequest) returns (RotateSigningSecretResponse) {}
+}
+
+// Speech defaults of an application; voices and models are catalog ids (provider/model-or-voice)
+message SpeechDefaults {
+  // Default voice, e.g. elevenlabs/rachel
+  string voice = 1;
+  // Default language (BCP 47), e.g. en-US
+  string language = 2;
+  // Speech-to-text model, e.g. deepgram/nova-3 (empty: the platform default)
+  string stt_model = 3;
+  // Text-to-speech model (empty: the voice's default)
+  string tts_model = 4;
+  // Silence timeout in milliseconds (0: the gateway default)
+  int32 silence_timeout_ms = 5;
+  // The Pacing policy's patience: low, normal or high (empty: normal)
+  string patience = 6;
+}
+
+// Caller and agent audio format for the fonoster protocol
+message AudioFormat {
+  // pcm16 or pcmu
+  string codec = 1;
+  // Sample rate in Hz: 8000, 16000 or 24000 (pcmu is 8000 only)
+  int32 rate = 2;
+}
+
+// Answering-machine detection: one amd.result event per call
+message AmdSettings {
+  // Classify the caller's first seconds of speech
+  bool enabled = 1;
+  // How much caller speech to classify, in milliseconds (0: 4000; 500 to 15000)
+  int32 window_ms = 2;
+}
+
+// A listen-only socket dialed for every session of the app
+message Listener {
+  // ws:// or wss:// address
+  string url = 1;
+  // inbound, outbound or both
+  string tracks = 2;
+}
+
+message RotateSigningSecretRequest {
+  // The reference to the application
+  string ref = 1;
+}
+
+message RotateSigningSecretResponse {
+  // The reference to the application
+  string ref = 1;
+  // The new secret; shown only in this response
+  string signing_secret = 2;
+  // The last characters of the secret
+  string signing_secret_hint = 3;
 }
 
 // The type of application
 enum ApplicationType {
-  // Programmable Voice
-  EXTERNAL = 0;
-  // Internal LLM based applications
+  // A stream: your own WebSocket server
+  STREAM = 0;
+  // An Autopilot agent (hosted by Fonoster)
   AUTOPILOT = 1;
 }
 
@@ -78,6 +134,26 @@ message Application {
   int32 created_at = 8;
   // Update time
   int32 updated_at = 9;
+  // The WebSocket URL the gateway dials
+  string url = 10;
+  // Stream protocol: fonoster or twilio
+  string protocol = 11;
+  // The last characters of the signing secret (the secret is never returned on reads)
+  string signing_secret_hint = 12;
+  // Speech defaults
+  SpeechDefaults speech = 13;
+  // Audio format (fonoster protocol)
+  AudioFormat audio = 14;
+  // App used when this one cannot be reached
+  string fallback_app_ref = 15;
+  // Message spoken when neither the app nor its fallback can be reached
+  string fallback_message = 16;
+  // Listen-only sockets
+  repeated Listener listeners = 17;
+  // Recording policy: off, on or consent (empty: the workspace's)
+  string recording = 18;
+  // Answering-machine detection (off when unset)
+  AmdSettings amd = 19;
 }
 
 // Request to create a new application
@@ -94,12 +170,34 @@ message CreateApplicationRequest {
   ProductContainer speech_to_text = 5;
   // Inference engine
   ProductContainer intelligence = 6;
+  // The WebSocket URL (Autopilot agents default to the hosted Autopilot)
+  string url = 7;
+  // fonoster or twilio (default fonoster)
+  string protocol = 8;
+  // Speech defaults
+  SpeechDefaults speech = 9;
+  // Audio format (fonoster protocol)
+  AudioFormat audio = 10;
+  // App used when this one cannot be reached
+  string fallback_app_ref = 11;
+  // Message spoken when neither the app nor its fallback can be reached
+  string fallback_message = 12;
+  // Listen-only sockets
+  repeated Listener listeners = 13;
+  // Recording policy: off, on or consent (empty: the workspace's)
+  string recording = 14;
+  // Answering-machine detection (off when unset)
+  AmdSettings amd = 15;
 }
 
 // Response for create application
 message CreateApplicationResponse {
   // Echo the reference of the application
   string ref = 1;
+  // The app's signing secret; shown only in this response
+  string signing_secret = 2;
+  // The last characters of the secret
+  string signing_secret_hint = 3;
 }
 
 // Request to get an application
@@ -140,12 +238,35 @@ message UpdateApplicationRequest {
   ProductContainer speech_to_text = 6;
   // Intelligence product
   ProductContainer intelligence = 7;
+  // The WebSocket URL (Autopilot agents default to the hosted Autopilot)
+  string url = 8;
+  // fonoster or twilio (default fonoster)
+  string protocol = 9;
+  // Speech defaults
+  SpeechDefaults speech = 10;
+  // Audio format (fonoster protocol)
+  AudioFormat audio = 11;
+  // App used when this one cannot be reached
+  string fallback_app_ref = 12;
+  // Message spoken when neither the app nor its fallback can be reached
+  string fallback_message = 13;
+  // Listen-only sockets
+  repeated Listener listeners = 14;
+  // Recording policy: off, on or consent (empty: the workspace's)
+  string recording = 15;
+  // Answering-machine detection (off when unset)
+  AmdSettings amd = 16;
 }
 
 // Response for update application
 message UpdateApplicationResponse {
   // Echo the reference of the application
   string ref = 1;
+  // A new signing secret when the update generated one (the app stopped being an Autopilot
+  // app); shown only in this response. Empty otherwise.
+  string signing_secret = 2;
+  // The last characters of the new secret (empty when there is none)
+  string signing_secret_hint = 3;
 }
 
 // Request to delete an application

package/dist/protos/authz.proto

@@ -23,19 +23,38 @@ package fonoster.authz.v1beta2;
 import "google/protobuf/struct.proto";
 import "google/protobuf/empty.proto";
 
-import "voice.proto";
-
 // Authentication service definition
 service Authz {
   // Check if a user has permission to perform an action
-  rpc CheckSessionAuthorized (fonoster.voice.v1beta2.CreateSessionRequest) returns (CheckSessionAuthorizedResponse) {}
+  rpc CheckSessionAuthorized (CheckSessionAuthorizedRequest) returns (CheckSessionAuthorizedResponse) {}
   // Check if a given accessKeyId has permission to access a method
   rpc CheckMethodAuthorized (CheckMethodAuthorizedRequest) returns (CheckMethodAuthorizedResponse) {}
   // Add billing meter event to an account
   rpc AddBillingMeterEvent (AddBillingMeterEventRequest) returns (google.protobuf.Empty) {}
 }
 
-// Response message for the CheckVoiceRequestAuthorized method
+// The call a session would serve. Field numbers match the retired
+// fonoster.voice.v1beta2.CreateSessionRequest, so existing authorization servers keep decoding it.
+message CheckSessionAuthorizedRequest {
+  string access_key_id = 1;
+  string app_ref = 2;
+  string endpoint = 3;
+  string ingress_number = 4;
+  string caller_name = 5;
+  string caller_number = 6;
+  string media_session_ref = 7;
+  string session_token = 8;
+  enum CallDirection {
+    FROM_PSTN = 0;
+    TO_PSTN = 1;
+    INTRA_NETWORK = 2;
+  }
+  CallDirection call_direction = 9;
+  map<string, string> metadata = 10;
+  string call_ref = 11;
+}
+
+// Response message for the CheckSessionAuthorized method
 message CheckSessionAuthorizedResponse {
   // The authorization server will look for one or more parameters in the request
   // to determine if the request is authorized. If the request is authorized, the

package/dist/protos/capabilities.proto

@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+syntax = "proto3";
+
+package fonoster.capabilities.v1beta2;
+
+import "google/protobuf/empty.proto";
+
+// What this deployment supports, from fonoster.yaml. Public (no credentials
+// needed) so sign-in screens can render from it; it never returns secrets.
+service Capabilities {
+  // Gets the deployment's capabilities
+  rpc GetCapabilities (google.protobuf.Empty) returns (GetCapabilitiesResponse) {}
+}
+
+message GitHubCapability {
+  string client_id = 1;
+  string authorize_url = 2;
+}
+
+message AuthCapabilities {
+  // Enabled sign-in methods: password | email_code | github
+  repeated string methods = 1;
+  // Who may create an account: invite | open
+  string signup = 2;
+  // Set when github is among the methods
+  GitHubCapability github = 3;
+}
+
+message BillingCapabilities {
+  bool enabled = 1;
+}
+
+message CostsCapabilities {
+  // none | usage | prices
+  string display = 1;
+}
+
+// Private regions (customer-run regions enrolled through the region hub).
+// The local public region always exists and is not reported here.
+message RegionsCapabilities {
+  // True when the operator configured the region hub and the region-signing
+  // key (regions.hub and regions.signingKey), so workspaces can enroll
+  // private regions. Never carries hub URLs or keys.
+  bool private = 1;
+}
+
+message SipEndpoint {
+  string host = 1;
+  int32 port = 2;
+  // udp | tcp | tls | ws | wss
+  string transport = 3;
+}
+
+message PortRange {
+  int32 min = 1;
+  int32 max = 2;
+}
+
+// Where carriers and softphones reach this deployment: the default public
+// region's endpoints (regions.public in fonoster.yaml). Addresses and ports
+// only, never credentials. Empty when the operator listed none.
+message ConnectionCapabilities {
+  repeated SipEndpoint sip = 1;
+  repeated string signaling_addresses = 2;
+  repeated string media_addresses = 3;
+  PortRange rtp_ports = 4;
+}
+
+message GetCapabilitiesResponse {
+  AuthCapabilities auth = 1;
+  BillingCapabilities billing = 2;
+  CostsCapabilities costs = 3;
+  string domain = 4;
+  string app_url = 5;
+  RegionsCapabilities regions = 6;
+  ConnectionCapabilities connection = 7;
+}