@fonoster/sipnet 0.36.0 → 0.38.0

package/dist/numbers/buildService.d.ts

@@ -19,8 +19,14 @@
 import { NumberPreconditionsCheck } from "@fonoster/common";
 import { ClientOptions } from "../types";
 import { NumberRouting } from "./engineRouting";
-/** `routing` picks the peer app-linked numbers point at (default: the roomr peer). */
-declare function buildService(clientOptions: ClientOptions, checkNumberPreconditions: NumberPreconditionsCheck, routing?: NumberRouting): {
+/**
+ * `routing` picks the peer app-linked numbers point at (default: the roomr peer). `twilioLink`
+ * is the install's PSTN root and public signaling addresses, for LinkTwilio.
+ */
+declare function buildService(clientOptions: ClientOptions, checkNumberPreconditions: NumberPreconditionsCheck, routing?: NumberRouting, twilioLink?: {
+    pstnRoot: string;
+    signalingAddresses: string[];
+}): {
     definition: {
         serviceName: string;
         pckg: string;
@@ -43,6 +49,9 @@ declare function buildService(clientOptions: ClientOptions, checkNumberPrecondit
         deleteNumber: (call: {
             request: unknown;
         }, callback: (error?: import("@fonoster/common").GrpcErrorMessage, response?: unknown) => void) => Promise<void>;
+        linkTwilio: (call: {
+            request: unknown;
+        }, callback: (error?: import("@fonoster/common").GrpcErrorMessage, response?: unknown) => void) => Promise<void>;
     };
 };
 export { buildService };

package/dist/numbers/buildService.js

@@ -8,11 +8,18 @@ const sdk_1 = __importDefault(require("@routr/sdk"));
 const checkRefs_1 = require("../resources/checkRefs");
 const createNumber_1 = require("./createNumber");
 const getNumber_1 = require("./getNumber");
+const linkTwilio_1 = require("./linkTwilio");
 const listNumbers_1 = require("./listNumbers");
 const operations_1 = require("./operations");
 const updateNumber_1 = require("./updateNumber");
-/** `routing` picks the peer app-linked numbers point at (default: the roomr peer). */
-function buildService(clientOptions, checkNumberPreconditions, routing) {
+/**
+ * `routing` picks the peer app-linked numbers point at (default: the roomr peer). `twilioLink`
+ * is the install's PSTN root and public signaling addresses, for LinkTwilio.
+ */
+function buildService(clientOptions, checkNumberPreconditions, routing, twilioLink = {
+    pstnRoot: "",
+    signalingAddresses: []
+}) {
     const client = new sdk_1.default.Numbers(clientOptions);
     const checkRefs = (0, checkRefs_1.createCheckRefs)((0, checkRefs_1.createRefLookups)(clientOptions));
     return {
@@ -27,7 +34,10 @@ function buildService(clientOptions, checkNumberPreconditions, routing) {
             updateNumber: (0, updateNumber_1.updateNumber)(client, checkNumberPreconditions, routing, checkRefs),
             getNumber: (0, getNumber_1.getNumber)(client),
             listNumbers: (0, listNumbers_1.listNumbers)(client),
-            deleteNumber: (0, operations_1.deleteNumber)(client)
+            deleteNumber: (0, operations_1.deleteNumber)(client),
+            linkTwilio: (0, linkTwilio_1.linkTwilio)(Object.assign({ numbers: client, trunks: new sdk_1.default.Trunks(clientOptions), credentials: new sdk_1.default.Credentials(clientOptions), checkNumberPreconditions,
+                routing,
+                checkRefs }, twilioLink))
         }
     };
 }

package/dist/numbers/linkTwilio.d.ts

@@ -0,0 +1,26 @@
+import { assignTwilioNumberToTrunk, GrpcErrorMessage, NumberPreconditionsCheck, provisionTwilioTrunk, removeOtherTwilioSipCredentials } from "@fonoster/common";
+import { CredentialsApi, NumbersApi, TrunkApi } from "@fonoster/types";
+import { CheckRefs } from "../resources/checkRefs";
+import { NumberRouting } from "./engineRouting";
+type TwilioLink = {
+    provisionTwilioTrunk: typeof provisionTwilioTrunk;
+    assignTwilioNumberToTrunk: typeof assignTwilioNumberToTrunk;
+    removeOtherTwilioSipCredentials: typeof removeOtherTwilioSipCredentials;
+};
+type LinkTwilioDeps = {
+    numbers: NumbersApi;
+    trunks: TrunkApi;
+    credentials: CredentialsApi;
+    checkNumberPreconditions: NumberPreconditionsCheck;
+    routing?: NumberRouting;
+    checkRefs?: CheckRefs;
+    /** Where carriers reach this install's trunks (`pstn.<domain>`). */
+    pstnRoot: string;
+    /** The install's public signaling addresses; only IPv4 literals are allowed in Twilio. */
+    signalingAddresses: string[];
+    twilio?: TwilioLink;
+};
+declare function linkTwilio(deps: LinkTwilioDeps): (call: {
+    request: unknown;
+}, callback: (error?: import("@fonoster/common").GrpcErrorMessage, response?: unknown) => void) => Promise<void>;
+export { linkTwilio, LinkTwilioDeps };

package/dist/numbers/linkTwilio.js

@@ -0,0 +1,228 @@
+"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.linkTwilio = linkTwilio;
+/**
+ * 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_crypto_1 = require("node:crypto");
+const node_net_1 = __importDefault(require("node:net"));
+const common_1 = require("@fonoster/common");
+const logger_1 = require("@fonoster/logger");
+const types_1 = require("@fonoster/types");
+const grpc_js_1 = require("@grpc/grpc-js");
+const phone_1 = require("phone");
+const checkRefs_1 = require("../resources/checkRefs");
+const paginationUtils_1 = require("../resources/paginationUtils");
+const operations_1 = require("../trunks/operations");
+const convertToRoutrNumber_1 = require("./convertToRoutrNumber");
+const twilioLinkErrorToGrpc_1 = require("./twilioLinkErrorToGrpc");
+const logger = (0, logger_1.getLogger)({ service: "sipnet", filePath: __filename });
+const TWILIO_PSTN_URI_BASE = "pstn.twilio.com";
+const PAGE_SIZE = 100;
+const PASSWORD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const isIpv4Entry = (address) => {
+    const [ip, prefix, ...rest] = address.split("/");
+    return (rest.length === 0 &&
+        node_net_1.default.isIPv4(ip) &&
+        (prefix === undefined || (/^\d{1,2}$/.test(prefix) && +prefix <= 32)));
+};
+function generatePassword() {
+    for (;;) {
+        const password = Array.from({ length: 24 }, () => PASSWORD_ALPHABET[(0, node_crypto_1.randomInt)(PASSWORD_ALPHABET.length)]).join("");
+        if (/[A-Z]/.test(password) &&
+            /[a-z]/.test(password) &&
+            /\d/.test(password)) {
+            return password;
+        }
+    }
+}
+// The caller's first resource that matches, through every page Routr has.
+function findOwned(list, accessKeyId, match) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let pageToken;
+        for (;;) {
+            const { items = [], nextPageToken } = yield list({
+                pageSize: PAGE_SIZE,
+                pageToken
+            });
+            const found = (0, paginationUtils_1.filterByAccessKeyId)(items, accessKeyId).find(match);
+            if (found || !nextPageToken || items.length < PAGE_SIZE) {
+                return found;
+            }
+            pageToken = nextPageToken;
+        }
+    });
+}
+function linkTwilio(deps) {
+    const { numbers, trunks, credentials, checkNumberPreconditions, routing, checkRefs, pstnRoot, twilio = {
+        provisionTwilioTrunk: common_1.provisionTwilioTrunk,
+        assignTwilioNumberToTrunk: common_1.assignTwilioNumberToTrunk,
+        removeOtherTwilioSipCredentials: common_1.removeOtherTwilioSipCredentials
+    } } = deps;
+    const aclEntries = deps.signalingAddresses.filter(isIpv4Entry);
+    const fn = (call, callback) => __awaiter(this, void 0, void 0, function* () {
+        const { request } = call;
+        const { phoneNumber, appRef, agentAor } = request;
+        const twilioCredentials = request.credentials;
+        const accessKeyId = (0, common_1.getAccessKeyIdFromCall)(call);
+        const label = accessKeyId.toLowerCase();
+        const inboundUri = `${label}.${pstnRoot}`;
+        const telUrl = `tel:${phoneNumber}`;
+        const context = {
+            accountSid: twilioCredentials.accountSid,
+            phoneNumber,
+            label
+        };
+        // Never the request itself: it carries the Twilio secret.
+        logger.verbose("call to linkTwilio", {
+            phoneNumber,
+            credentialKind: "authToken" in twilioCredentials && twilioCredentials.authToken
+                ? "authToken"
+                : "apiKey"
+        });
+        try {
+            // Validates that the appRef exists in the caller's workspace (RV-B4)
+            yield checkNumberPreconditions({ appRef, accessKeyId });
+        }
+        catch (e) {
+            // The contract reports an app outside the workspace as NOT_FOUND, with the usual message.
+            if (e instanceof common_1.GrpcError && e.code === grpc_js_1.status.INVALID_ARGUMENT) {
+                callback({ code: grpc_js_1.status.NOT_FOUND, message: e.message });
+                return;
+            }
+            throw e;
+        }
+        yield (checkRefs === null || checkRefs === void 0 ? void 0 : checkRefs(accessKeyId, (0, checkRefs_1.numberRefs)(request)));
+        if (aclEntries.length === 0) {
+            callback({
+                code: grpc_js_1.status.FAILED_PRECONDITION,
+                message: "This install has no public SIP address to allow in Twilio"
+            });
+            return;
+        }
+        const sipCredential = {
+            username: `fonoster-${(0, node_crypto_1.randomBytes)(4).toString("hex")}`,
+            password: generatePassword()
+        };
+        let twilioTrunkSid;
+        try {
+            ({ twilioTrunkSid } = yield twilio.provisionTwilioTrunk(twilioCredentials, {
+                phoneNumber,
+                label,
+                originationUri: `sip:${inboundUri}`,
+                aclEntries,
+                sipCredential
+            }));
+        }
+        catch (e) {
+            callback((0, twilioLinkErrorToGrpc_1.twilioLinkErrorToGrpc)(e, context));
+            return;
+        }
+        const { ref: credentialsRef } = yield credentials.createCredentials(Object.assign(Object.assign({ name: `Twilio ${label}` }, sipCredential), { extended: { accessKeyId } }));
+        const trunk = yield findOwned((r) => trunks.listTrunks(r), accessKeyId, (t) => t.inboundUri === inboundUri);
+        let trunkRef;
+        if (trunk) {
+            yield trunks.updateTrunk((0, operations_1.mergeTrunkUpdate)({ ref: trunk.ref, outboundCredentialsRef: credentialsRef }, trunk));
+            trunkRef = trunk.ref;
+        }
+        else {
+            ({ ref: trunkRef } = yield trunks.createTrunk({
+                name: "Twilio Trunk",
+                inboundUri,
+                sendRegister: false,
+                outboundCredentialsRef: credentialsRef,
+                uris: [
+                    {
+                        host: `${label}.${TWILIO_PSTN_URI_BASE}`,
+                        port: 5060,
+                        transport: types_1.Transport.UDP,
+                        enabled: true,
+                        weight: 10,
+                        priority: 10
+                    }
+                ],
+                extended: { accessKeyId }
+            }));
+        }
+        const number = yield findOwned((r) => numbers.listNumbers(r), accessKeyId, (n) => n.telUrl === telUrl);
+        const appPeerAor = routing && appRef ? yield routing.aorFor({ appRef, telUrl }) : undefined;
+        let ref;
+        if (number) {
+            yield numbers.updateNumber((0, convertToRoutrNumber_1.convertToRoutrNumberUpdate)({
+                ref: number.ref,
+                name: request.name || number.name,
+                trunkRef,
+                appRef,
+                agentAor
+            }, appPeerAor));
+            ref = number.ref;
+        }
+        else {
+            const { countryIso2, countryIso3 } = (0, phone_1.phone)(phoneNumber);
+            ({ ref } = yield numbers.createNumber((0, convertToRoutrNumber_1.convertToRoutrNumber)({
+                name: request.name || phoneNumber,
+                telUrl,
+                city: "unknown",
+                country: countryIso3,
+                countryIsoCode: countryIso2,
+                trunkRef,
+                appRef,
+                agentAor
+            }, accessKeyId, appPeerAor)));
+        }
+        // The last write to Twilio: until it succeeds, the number keeps its previous routing.
+        try {
+            yield twilio.assignTwilioNumberToTrunk(twilioCredentials, {
+                phoneNumber,
+                twilioTrunkSid
+            });
+        }
+        catch (e) {
+            callback((0, twilioLinkErrorToGrpc_1.twilioLinkErrorToGrpc)(e, context));
+            return;
+        }
+        try {
+            yield twilio.removeOtherTwilioSipCredentials(twilioCredentials, {
+                label,
+                keepUsername: sipCredential.username
+            });
+            if (trunk === null || trunk === void 0 ? void 0 : trunk.outboundCredentialsRef) {
+                yield credentials.deleteCredentials(trunk.outboundCredentialsRef);
+            }
+        }
+        catch (_a) {
+            logger.warn("could not remove the previous SIP credentials", {
+                phoneNumber
+            });
+        }
+        callback(null, { ref, trunkRef });
+    });
+    return (0, common_1.withErrorHandlingAndValidation)(fn, common_1.Validators.linkTwilioRequestSchema);
+}

package/dist/numbers/twilioLinkErrorToGrpc.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+import { GrpcErrorMessage } from "@fonoster/common";
+/**
+ * The gRPC error for a failed Twilio call. Clients place errors by these messages, so they are
+ * part of the contract. Twilio's own text never reaches the caller or the logs, and anything
+ * unrecognized is reported as Twilio being unavailable.
+ */
+declare function twilioLinkErrorToGrpc(error: unknown, context: {
+    accountSid: string;
+    phoneNumber: string;
+    label: string;
+}): GrpcErrorMessage;
+export { twilioLinkErrorToGrpc };

package/dist/numbers/twilioLinkErrorToGrpc.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.twilioLinkErrorToGrpc = twilioLinkErrorToGrpc;
+/**
+ * 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 common_1 = require("@fonoster/common");
+const grpc_js_1 = require("@grpc/grpc-js");
+const UNAVAILABLE = {
+    code: grpc_js_1.status.UNAVAILABLE,
+    message: "Twilio is unavailable; try again"
+};
+// What a key without the permission for a Twilio call can't do, by the call's prefix
+function missingPermission(step = "") {
+    if (step.startsWith("sip.")) {
+        return "manage SIP IP access control lists and credential lists";
+    }
+    if (step.startsWith("incomingPhoneNumbers.")) {
+        return "read or update phone numbers";
+    }
+    return "manage Elastic SIP Trunking";
+}
+/**
+ * The gRPC error for a failed Twilio call. Clients place errors by these messages, so they are
+ * part of the contract. Twilio's own text never reaches the caller or the logs, and anything
+ * unrecognized is reported as Twilio being unavailable.
+ */
+function twilioLinkErrorToGrpc(error, context) {
+    if (!(error instanceof common_1.TwilioLinkError)) {
+        return UNAVAILABLE;
+    }
+    const failedPrecondition = (message) => ({
+        code: grpc_js_1.status.FAILED_PRECONDITION,
+        message
+    });
+    switch (error.reason) {
+        case "INVALID_CREDENTIALS":
+            return { code: grpc_js_1.status.INVALID_ARGUMENT, message: error.message };
+        case "CREDENTIALS_REFUSED":
+            return failedPrecondition("Twilio didn't accept these credentials");
+        case "PERMISSION_MISSING":
+            return failedPrecondition(`This Twilio key can't ${missingPermission(error.step)}. Twilio's Restricted keys can't link numbers; use a Standard API key or the Auth Token`);
+        case "NUMBER_NOT_FOUND":
+            return failedPrecondition(`${context.phoneNumber} isn't in Twilio account AC…${context.accountSid.slice(-4)}`);
+        case "DOMAIN_TAKEN":
+            return failedPrecondition(`Another Twilio account already uses ${context.label}.pstn.twilio.com; link from the Twilio account this workspace linked first`);
+        default:
+            return UNAVAILABLE;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/sipnet",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Routr-based SIP stack",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -19,12 +19,13 @@
     "fonoster": "./dist/index.js"
   },
   "dependencies": {
-    "@fonoster/common": "^0.36.0",
-    "@fonoster/identity": "^0.36.0",
-    "@fonoster/logger": "^0.36.0",
-    "@fonoster/types": "^0.36.0",
+    "@fonoster/common": "^0.38.0",
+    "@fonoster/identity": "^0.38.0",
+    "@fonoster/logger": "^0.38.0",
+    "@fonoster/types": "^0.38.0",
     "@grpc/grpc-js": "~1.14.6",
     "@routr/sdk": "2.24.0",
+    "phone": "^3.1.72",
     "zod": "^3.23.8"
   },
   "files": [
@@ -40,5 +41,5 @@
   "bugs": {
     "url": "https://github.com/fonoster/fonoster/issues"
   },
-  "gitHead": "939b219d83506d7480c60813b3e58034cbede14f"
+  "gitHead": "111977a48870cf2b4e29a5ed644b95195217384f"
 }