@signalwire/sdk 2.0.4 → 3.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +785 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +550 -163
- package/dist/AgentBase.js +1640 -514
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +21 -0
- package/dist/AgentServer.js +154 -47
- package/dist/AgentServer.js.map +1 -1
- package/dist/AuthHandler.d.ts +14 -2
- package/dist/AuthHandler.js +7 -2
- package/dist/AuthHandler.js.map +1 -1
- package/dist/ConfigLoader.d.ts +5 -13
- package/dist/ConfigLoader.js +15 -29
- package/dist/ConfigLoader.js.map +1 -1
- package/dist/ContextBuilder.d.ts +202 -9
- package/dist/ContextBuilder.js +219 -36
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/DataMap.d.ts +158 -45
- package/dist/DataMap.js +167 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +277 -83
- package/dist/FunctionResult.js +444 -116
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +30 -5
- package/dist/Logger.js +77 -19
- package/dist/Logger.js.map +1 -1
- package/dist/POM/PromptObjectModel.d.ts +163 -0
- package/dist/POM/PromptObjectModel.js +481 -0
- package/dist/POM/PromptObjectModel.js.map +1 -0
- package/dist/ParameterSchema.d.ts +306 -0
- package/dist/ParameterSchema.js +251 -0
- package/dist/ParameterSchema.js.map +1 -0
- package/dist/PlatformContracts.d.ts +21 -0
- package/dist/PlatformContracts.generated.d.ts +109 -0
- package/dist/PlatformContracts.generated.js +8 -0
- package/dist/PlatformContracts.generated.js.map +1 -0
- package/dist/PlatformContracts.js +2 -0
- package/dist/PlatformContracts.js.map +1 -0
- package/dist/PomBuilder.d.ts +28 -0
- package/dist/PomBuilder.js +81 -3
- package/dist/PomBuilder.js.map +1 -1
- package/dist/PostPrompt.d.ts +110 -0
- package/dist/PostPrompt.js +204 -0
- package/dist/PostPrompt.js.map +1 -0
- package/dist/PromptManager.d.ts +29 -1
- package/dist/PromptManager.js +37 -1
- package/dist/PromptManager.js.map +1 -1
- package/dist/PublicFetch.d.ts +132 -0
- package/dist/PublicFetch.js +311 -0
- package/dist/PublicFetch.js.map +1 -0
- package/dist/RobotsTxt.d.ts +41 -0
- package/dist/RobotsTxt.js +152 -0
- package/dist/RobotsTxt.js.map +1 -0
- package/dist/SWMLHandler.js.map +1 -1
- package/dist/SWMLService.d.ts +265 -66
- package/dist/SWMLService.js +652 -112
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.d.ts +115 -2
- package/dist/SchemaUtils.js +444 -12
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SecurityUtils.d.ts +55 -8
- package/dist/SecurityUtils.js +162 -49
- package/dist/SecurityUtils.js.map +1 -1
- package/dist/ServerlessAdapter.d.ts +156 -7
- package/dist/ServerlessAdapter.js +399 -42
- package/dist/ServerlessAdapter.js.map +1 -1
- package/dist/SessionManager.d.ts +11 -2
- package/dist/SessionManager.js +50 -18
- package/dist/SessionManager.js.map +1 -1
- package/dist/SslConfig.d.ts +2 -1
- package/dist/SslConfig.js +4 -1
- package/dist/SslConfig.js.map +1 -1
- package/dist/SwaigActions.generated.d.ts +23 -0
- package/dist/SwaigActions.generated.js +8 -0
- package/dist/SwaigActions.generated.js.map +1 -0
- package/dist/SwaigContracts.d.ts +15 -0
- package/dist/SwaigContracts.generated.d.ts +264 -0
- package/dist/SwaigContracts.generated.js +12 -0
- package/dist/SwaigContracts.generated.js.map +1 -0
- package/dist/SwaigContracts.js +2 -0
- package/dist/SwaigContracts.js.map +1 -0
- package/dist/SwaigFunction.d.ts +110 -4
- package/dist/SwaigFunction.js +151 -19
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/SwmlBuilder.d.ts +68 -19
- package/dist/SwmlBuilder.js +74 -38
- package/dist/SwmlBuilder.js.map +1 -1
- package/dist/SwmlVerbMethods.generated.d.ts +41 -4
- package/dist/SwmlVerbMethods.generated.js +1 -1
- package/dist/TypeInference.d.ts +39 -3
- package/dist/TypeInference.js +256 -16
- package/dist/TypeInference.js.map +1 -1
- package/dist/WebService.d.ts +79 -11
- package/dist/WebService.js +320 -109
- package/dist/WebService.js.map +1 -1
- package/dist/WebhookMiddleware.d.ts +119 -0
- package/dist/WebhookMiddleware.js +271 -0
- package/dist/WebhookMiddleware.js.map +1 -0
- package/dist/WebhookValidator.d.ts +92 -0
- package/dist/WebhookValidator.js +409 -0
- package/dist/WebhookValidator.js.map +1 -0
- package/dist/agents/BedrockAgent.d.ts +162 -0
- package/dist/agents/BedrockAgent.js +323 -0
- package/dist/agents/BedrockAgent.js.map +1 -0
- package/dist/ai-chat/AIChatClient.d.ts +316 -0
- package/dist/ai-chat/AIChatClient.js +535 -0
- package/dist/ai-chat/AIChatClient.js.map +1 -0
- package/dist/ai-chat/ChatGateway.d.ts +408 -0
- package/dist/ai-chat/ChatGateway.js +747 -0
- package/dist/ai-chat/ChatGateway.js.map +1 -0
- package/dist/ai-chat/HandoffRouter.d.ts +282 -0
- package/dist/ai-chat/HandoffRouter.js +518 -0
- package/dist/ai-chat/HandoffRouter.js.map +1 -0
- package/dist/ai-chat/index.d.ts +12 -0
- package/dist/ai-chat/index.js +10 -0
- package/dist/ai-chat/index.js.map +1 -0
- package/dist/capabilities.d.ts +64 -0
- package/dist/capabilities.js +95 -0
- package/dist/capabilities.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +32 -6
- package/dist/cli/agent-loader.js +95 -34
- package/dist/cli/agent-loader.js.map +1 -1
- package/dist/cli/datamap-exec.d.ts +175 -0
- package/dist/cli/datamap-exec.js +1284 -0
- package/dist/cli/datamap-exec.js.map +1 -0
- package/dist/cli/function-args.d.ts +40 -0
- package/dist/cli/function-args.js +146 -0
- package/dist/cli/function-args.js.map +1 -0
- package/dist/cli/simulation.d.ts +99 -0
- package/dist/cli/simulation.js +490 -0
- package/dist/cli/simulation.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +12 -25
- package/dist/cli/swaig-test.js +935 -367
- package/dist/cli/swaig-test.js.map +1 -1
- package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
- package/dist/cli/tsdocs/agentsNote.js +92 -0
- package/dist/cli/tsdocs/agentsNote.js.map +1 -0
- package/dist/cli/tsdocs/api-index.json +1 -0
- package/dist/cli/tsdocs/api.d.ts +91 -0
- package/dist/cli/tsdocs/api.js +372 -0
- package/dist/cli/tsdocs/api.js.map +1 -0
- package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
- package/dist/cli/tsdocs/apiTypes.js +7 -0
- package/dist/cli/tsdocs/apiTypes.js.map +1 -0
- package/dist/cli/tsdocs/bin.d.ts +6 -0
- package/dist/cli/tsdocs/bin.js +23 -0
- package/dist/cli/tsdocs/bin.js.map +1 -0
- package/dist/cli/tsdocs/files.d.ts +108 -0
- package/dist/cli/tsdocs/files.js +287 -0
- package/dist/cli/tsdocs/files.js.map +1 -0
- package/dist/cli/tsdocs/index.d.ts +28 -0
- package/dist/cli/tsdocs/index.js +307 -0
- package/dist/cli/tsdocs/index.js.map +1 -0
- package/dist/cli/tsdocs/live.d.ts +41 -0
- package/dist/cli/tsdocs/live.js +202 -0
- package/dist/cli/tsdocs/live.js.map +1 -0
- package/dist/cli/tsdocs/locate.d.ts +51 -0
- package/dist/cli/tsdocs/locate.js +75 -0
- package/dist/cli/tsdocs/locate.js.map +1 -0
- package/dist/cli/tsdocs/render.d.ts +75 -0
- package/dist/cli/tsdocs/render.js +323 -0
- package/dist/cli/tsdocs/render.js.map +1 -0
- package/dist/cli/tsdocs/topics.d.ts +43 -0
- package/dist/cli/tsdocs/topics.js +916 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +102 -39
- package/dist/index.js +107 -30
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +229 -155
- package/dist/livewire/index.js +298 -195
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +65 -0
- package/dist/prefabs/CallSessionStore.d.ts +52 -0
- package/dist/prefabs/CallSessionStore.js +72 -0
- package/dist/prefabs/CallSessionStore.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +13 -1
- package/dist/prefabs/ConciergeAgent.js +36 -31
- package/dist/prefabs/ConciergeAgent.js.map +1 -1
- package/dist/prefabs/FAQBotAgent.d.ts +9 -1
- package/dist/prefabs/FAQBotAgent.js +113 -47
- package/dist/prefabs/FAQBotAgent.js.map +1 -1
- package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
- package/dist/prefabs/InfoGathererAgent.js +67 -58
- package/dist/prefabs/InfoGathererAgent.js.map +1 -1
- package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
- package/dist/prefabs/ReceptionistAgent.js +39 -31
- package/dist/prefabs/ReceptionistAgent.js.map +1 -1
- package/dist/prefabs/SurveyAgent.d.ts +22 -4
- package/dist/prefabs/SurveyAgent.js +84 -68
- package/dist/prefabs/SurveyAgent.js.map +1 -1
- package/dist/relay/Action.d.ts +44 -21
- package/dist/relay/Action.js +75 -17
- package/dist/relay/Action.js.map +1 -1
- package/dist/relay/Call.d.ts +312 -47
- package/dist/relay/Call.js +369 -18
- package/dist/relay/Call.js.map +1 -1
- package/dist/relay/Deferred.js.map +1 -1
- package/dist/relay/Message.d.ts +26 -5
- package/dist/relay/Message.js +36 -6
- package/dist/relay/Message.js.map +1 -1
- package/dist/relay/RelayClient.d.ts +79 -14
- package/dist/relay/RelayClient.js +268 -61
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayError.d.ts +14 -0
- package/dist/relay/RelayError.js +15 -0
- package/dist/relay/RelayError.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +96 -65
- package/dist/relay/RelayEvent.js +85 -56
- package/dist/relay/RelayEvent.js.map +1 -1
- package/dist/relay/closedSets.d.ts +111 -0
- package/dist/relay/closedSets.js +83 -0
- package/dist/relay/closedSets.js.map +1 -0
- package/dist/relay/index.d.ts +3 -1
- package/dist/relay/index.js +1 -0
- package/dist/relay/index.js.map +1 -1
- package/dist/relay/normalize.js.map +1 -1
- package/dist/relay/protocol.types.generated.d.ts +1195 -0
- package/dist/relay/protocol.types.generated.js +8 -0
- package/dist/relay/protocol.types.generated.js.map +1 -0
- package/dist/relay/types.d.ts +81 -39
- package/dist/rest/HttpClient.d.ts +36 -8
- package/dist/rest/HttpClient.js +233 -40
- package/dist/rest/HttpClient.js.map +1 -1
- package/dist/rest/RequestOptions.d.ts +110 -0
- package/dist/rest/RequestOptions.js +113 -0
- package/dist/rest/RequestOptions.js.map +1 -0
- package/dist/rest/RestError.d.ts +52 -6
- package/dist/rest/RestError.js +89 -5
- package/dist/rest/RestError.js.map +1 -1
- package/dist/rest/base/CrudResource.d.ts +16 -26
- package/dist/rest/base/CrudResource.js +19 -33
- package/dist/rest/base/CrudResource.js.map +1 -1
- package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
- package/dist/rest/base/CrudWithAddresses.js +2 -2
- package/dist/rest/base/CrudWithAddresses.js.map +1 -1
- package/dist/rest/base/FabricResource.d.ts +15 -0
- package/dist/rest/base/FabricResource.js +16 -0
- package/dist/rest/base/FabricResource.js.map +1 -0
- package/dist/rest/base/ReadResource.d.ts +62 -0
- package/dist/rest/base/ReadResource.js +69 -0
- package/dist/rest/base/ReadResource.js.map +1 -0
- package/dist/rest/callHandler.d.ts +63 -0
- package/dist/rest/callHandler.js +62 -0
- package/dist/rest/callHandler.js.map +1 -0
- package/dist/rest/index.d.ts +19 -76
- package/dist/rest/index.js +49 -120
- package/dist/rest/index.js.map +1 -1
- package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
- package/dist/rest/namespaces/_client_tree_generated.js +171 -0
- package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +3 -42
- package/dist/rest/namespaces/addresses.js +3 -50
- package/dist/rest/namespaces/addresses.js.map +1 -1
- package/dist/rest/namespaces/calling.d.ts +6 -378
- package/dist/rest/namespaces/calling.js +6 -473
- package/dist/rest/namespaces/calling.js.map +1 -1
- package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
- package/dist/rest/namespaces/calling.resources.generated.js +477 -0
- package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
- package/dist/rest/namespaces/calling.types.generated.js +8 -0
- package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +4 -18
- package/dist/rest/namespaces/chat.js +4 -21
- package/dist/rest/namespaces/chat.js.map +1 -1
- package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/chat.resources.generated.js +29 -0
- package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
- package/dist/rest/namespaces/chat.types.generated.js +8 -0
- package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +6 -62
- package/dist/rest/namespaces/datasphere.js +6 -72
- package/dist/rest/namespaces/datasphere.js.map +1 -1
- package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
- package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
- package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +11 -273
- package/dist/rest/namespaces/fabric.js +14 -363
- package/dist/rest/namespaces/fabric.js.map +1 -1
- package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
- package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
- package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
- package/dist/rest/namespaces/fabric.types.generated.js +8 -0
- package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/fax.resources.generated.js +14 -0
- package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/fax.types.generated.js +8 -0
- package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
- package/dist/rest/namespaces/imported-numbers.js +3 -21
- package/dist/rest/namespaces/imported-numbers.js.map +1 -1
- package/dist/rest/namespaces/logs.d.ts +10 -101
- package/dist/rest/namespaces/logs.js +10 -128
- package/dist/rest/namespaces/logs.js.map +1 -1
- package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/logs.resources.generated.js +17 -0
- package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/logs.types.generated.js +8 -0
- package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +3 -25
- package/dist/rest/namespaces/lookup.js +3 -27
- package/dist/rest/namespaces/lookup.js.map +1 -1
- package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/message.resources.generated.js +14 -0
- package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
- package/dist/rest/namespaces/message.types.generated.js +8 -0
- package/dist/rest/namespaces/message.types.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
- package/dist/rest/namespaces/messages.resources.generated.js +44 -0
- package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
- package/dist/rest/namespaces/messages.types.generated.js +8 -0
- package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +3 -42
- package/dist/rest/namespaces/mfa.js +3 -49
- package/dist/rest/namespaces/mfa.js.map +1 -1
- package/dist/rest/namespaces/number-groups.d.ts +3 -45
- package/dist/rest/namespaces/number-groups.js +3 -53
- package/dist/rest/namespaces/number-groups.js.map +1 -1
- package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
- package/dist/rest/namespaces/phone-numbers.js +9 -63
- package/dist/rest/namespaces/phone-numbers.js.map +1 -1
- package/dist/rest/namespaces/project.d.ts +6 -42
- package/dist/rest/namespaces/project.js +6 -51
- package/dist/rest/namespaces/project.js.map +1 -1
- package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
- package/dist/rest/namespaces/project.resources.generated.js +44 -0
- package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
- package/dist/rest/namespaces/project.types.generated.js +8 -0
- package/dist/rest/namespaces/project.types.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/projects.resources.generated.js +25 -0
- package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
- package/dist/rest/namespaces/projects.types.generated.js +8 -0
- package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +4 -18
- package/dist/rest/namespaces/pubsub.js +4 -21
- package/dist/rest/namespaces/pubsub.js.map +1 -1
- package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
- package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
- package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +3 -38
- package/dist/rest/namespaces/queues.js +3 -44
- package/dist/rest/namespaces/queues.js.map +1 -1
- package/dist/rest/namespaces/recordings.d.ts +3 -34
- package/dist/rest/namespaces/recordings.js +3 -40
- package/dist/rest/namespaces/recordings.js.map +1 -1
- package/dist/rest/namespaces/registry.d.ts +6 -137
- package/dist/rest/namespaces/registry.js +6 -173
- package/dist/rest/namespaces/registry.js.map +1 -1
- package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +3 -35
- package/dist/rest/namespaces/short-codes.js +3 -41
- package/dist/rest/namespaces/short-codes.js.map +1 -1
- package/dist/rest/namespaces/sip-profile.d.ts +3 -24
- package/dist/rest/namespaces/sip-profile.js +3 -29
- package/dist/rest/namespaces/sip-profile.js.map +1 -1
- package/dist/rest/namespaces/verified-callers.d.ts +3 -29
- package/dist/rest/namespaces/verified-callers.js +3 -34
- package/dist/rest/namespaces/verified-callers.js.map +1 -1
- package/dist/rest/namespaces/video.d.ts +10 -227
- package/dist/rest/namespaces/video.js +10 -288
- package/dist/rest/namespaces/video.js.map +1 -1
- package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
- package/dist/rest/namespaces/video.resources.generated.js +171 -0
- package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
- package/dist/rest/namespaces/video.types.generated.js +8 -0
- package/dist/rest/namespaces/video.types.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/voice.resources.generated.js +17 -0
- package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
- package/dist/rest/namespaces/voice.types.generated.js +8 -0
- package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
- package/dist/rest/pagination.d.ts +5 -1
- package/dist/rest/pagination.js +40 -20
- package/dist/rest/pagination.js.map +1 -1
- package/dist/rest/types.d.ts +21 -3
- package/dist/schema.json +299 -98
- package/dist/skills/SkillBase.d.ts +97 -20
- package/dist/skills/SkillBase.js +100 -17
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/skills/SkillManager.d.ts +66 -13
- package/dist/skills/SkillManager.js +101 -20
- package/dist/skills/SkillManager.js.map +1 -1
- package/dist/skills/SkillName.d.ts +44 -0
- package/dist/skills/SkillName.js +2 -0
- package/dist/skills/SkillName.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +47 -7
- package/dist/skills/SkillRegistry.js +85 -13
- package/dist/skills/SkillRegistry.js.map +1 -1
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
- package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
- package/dist/skills/builtin/ask_claude.d.ts +14 -4
- package/dist/skills/builtin/ask_claude.js +36 -14
- package/dist/skills/builtin/ask_claude.js.map +1 -1
- package/dist/skills/builtin/claude_skills.d.ts +3 -1
- package/dist/skills/builtin/claude_skills.js +19 -15
- package/dist/skills/builtin/claude_skills.js.map +1 -1
- package/dist/skills/builtin/custom_skills.d.ts +10 -3
- package/dist/skills/builtin/custom_skills.js +26 -9
- package/dist/skills/builtin/custom_skills.js.map +1 -1
- package/dist/skills/builtin/datasphere.d.ts +5 -3
- package/dist/skills/builtin/datasphere.js +34 -25
- package/dist/skills/builtin/datasphere.js.map +1 -1
- package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
- package/dist/skills/builtin/datasphere_serverless.js +17 -6
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
- package/dist/skills/builtin/datetime.d.ts +3 -1
- package/dist/skills/builtin/datetime.js +11 -7
- package/dist/skills/builtin/datetime.js.map +1 -1
- package/dist/skills/builtin/google_maps.d.ts +29 -14
- package/dist/skills/builtin/google_maps.js +89 -269
- package/dist/skills/builtin/google_maps.js.map +1 -1
- package/dist/skills/builtin/index.d.ts +8 -6
- package/dist/skills/builtin/index.js +8 -6
- package/dist/skills/builtin/index.js.map +1 -1
- package/dist/skills/builtin/info_gatherer.d.ts +4 -2
- package/dist/skills/builtin/info_gatherer.js +20 -12
- package/dist/skills/builtin/info_gatherer.js.map +1 -1
- package/dist/skills/builtin/joke.d.ts +16 -6
- package/dist/skills/builtin/joke.js +54 -37
- package/dist/skills/builtin/joke.js.map +1 -1
- package/dist/skills/builtin/math.d.ts +3 -1
- package/dist/skills/builtin/math.js +14 -9
- package/dist/skills/builtin/math.js.map +1 -1
- package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
- package/dist/skills/builtin/mcp_gateway.js +77 -46
- package/dist/skills/builtin/mcp_gateway.js.map +1 -1
- package/dist/skills/builtin/native_vector_search.d.ts +19 -5
- package/dist/skills/builtin/native_vector_search.js +179 -61
- package/dist/skills/builtin/native_vector_search.js.map +1 -1
- package/dist/skills/builtin/play_background_file.d.ts +21 -15
- package/dist/skills/builtin/play_background_file.js +43 -122
- package/dist/skills/builtin/play_background_file.js.map +1 -1
- package/dist/skills/builtin/spider.d.ts +46 -1
- package/dist/skills/builtin/spider.js +317 -101
- package/dist/skills/builtin/spider.js.map +1 -1
- package/dist/skills/builtin/swml_transfer.d.ts +14 -3
- package/dist/skills/builtin/swml_transfer.js +45 -24
- package/dist/skills/builtin/swml_transfer.js.map +1 -1
- package/dist/skills/builtin/weather_api.d.ts +24 -13
- package/dist/skills/builtin/weather_api.js +57 -31
- package/dist/skills/builtin/weather_api.js.map +1 -1
- package/dist/skills/builtin/web_search.d.ts +48 -10
- package/dist/skills/builtin/web_search.js +301 -84
- package/dist/skills/builtin/web_search.js.map +1 -1
- package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
- package/dist/skills/builtin/wikipedia_search.js +32 -14
- package/dist/skills/builtin/wikipedia_search.js.map +1 -1
- package/dist/skills/index.d.ts +3 -2
- package/dist/skills/index.js +1 -1
- package/dist/skills/index.js.map +1 -1
- package/dist/swml_verbs_generated.d.ts +2824 -0
- package/dist/swml_verbs_generated.js +12 -0
- package/dist/swml_verbs_generated.js.map +1 -0
- package/dist/types.d.ts +65 -6
- package/dist/web.d.ts +27 -0
- package/dist/web.js +20 -0
- package/dist/web.js.map +1 -0
- package/docs/agent-guide.md +1034 -0
- package/docs/ai_chat.md +560 -0
- package/docs/api-reference.md +3534 -0
- package/docs/architecture.md +846 -0
- package/docs/bedrock_agent.md +411 -0
- package/docs/cli-guide.md +403 -0
- package/docs/cloud_functions_guide.md +399 -0
- package/docs/configuration.md +548 -0
- package/docs/contexts-guide.md +884 -0
- package/docs/datamap-guide.md +1160 -0
- package/docs/developer_pain_points.md +548 -0
- package/docs/llm_parameters.md +298 -0
- package/docs/mcp_gateway_reference.md +354 -0
- package/docs/mcp_integration.md +162 -0
- package/docs/pgi_agent_guide.md +1820 -0
- package/docs/prefabs-guide.md +815 -0
- package/docs/programmatically_governed_inference.md +301 -0
- package/docs/sdk_features.md +501 -0
- package/docs/security.md +559 -0
- package/docs/serverless-guide.md +520 -0
- package/docs/skills-guide.md +1223 -0
- package/docs/skills-system.md +405 -0
- package/docs/skills_parameter_schema.md +417 -0
- package/docs/swaig-reference.md +1938 -0
- package/docs/swml_service_guide.md +573 -0
- package/docs/third_party_skills.md +410 -0
- package/docs/web_service.md +666 -0
- package/examples/README.md +202 -0
- package/examples/advanced-datamap.ts +108 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +95 -0
- package/examples/call-flow.ts +65 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +51 -0
- package/examples/datasphere-multi-instance.ts +66 -0
- package/examples/datasphere-serverless-env.ts +87 -0
- package/examples/datasphere-webhook-env.ts +65 -0
- package/examples/datasphere.ts +56 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +95 -0
- package/examples/gather-per-question-functions-demo.ts +139 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +75 -0
- package/examples/mcp-agent.ts +89 -0
- package/examples/mcp-gateway.ts +81 -0
- package/examples/multi-agent.ts +80 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pgi/case-domain.ts +114 -0
- package/examples/pgi/serve.ts +16 -0
- package/examples/pgi/support-agent.ts +265 -0
- package/examples/pom-prompt.ts +70 -0
- package/examples/prefab-concierge.ts +42 -0
- package/examples/prefab-faq.ts +58 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +69 -0
- package/examples/quickstart-agent.ts +29 -0
- package/examples/quickstart-relay.ts +25 -0
- package/examples/quickstart-rest.ts +25 -0
- package/examples/record-call.ts +65 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +93 -0
- package/examples/serverless-lambda.ts +43 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +41 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +193 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/swmlservice_ai_sidecar.ts +104 -0
- package/examples/swmlservice_swaig_standalone.ts +79 -0
- package/examples/tap.ts +67 -0
- package/examples/typed-tools.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +75 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +164 -0
- package/livewire/docs/migration-guide.md +251 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +196 -0
- package/livewire/examples/livewire-multi-tool.ts +121 -0
- package/package.json +88 -13
- package/relay/README.md +101 -0
- package/relay/docs/call-methods.md +622 -0
- package/relay/docs/client-reference.md +281 -0
- package/relay/docs/events.md +193 -0
- package/relay/docs/getting-started.md +221 -0
- package/relay/docs/guide.md +386 -0
- package/relay/docs/messaging.md +246 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +74 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +141 -0
- package/rest/docs/calling.md +313 -0
- package/rest/docs/client-reference.md +149 -0
- package/rest/docs/fabric.md +192 -0
- package/rest/docs/getting-started.md +138 -0
- package/rest/docs/guide.md +421 -0
- package/rest/docs/namespaces.md +367 -0
- package/rest/docs/phone-binding.md +116 -0
- package/rest/examples/rest-10dlc-registration.ts +177 -0
- package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
- package/rest/examples/rest-calling-play-and-record.ts +98 -0
- package/rest/examples/rest-client.ts +59 -0
- package/rest/examples/rest-datasphere-search.ts +81 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
- package/rest/examples/rest-manage-resources.ts +64 -0
- package/rest/examples/rest-phone-number-management.ts +200 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/tutorial/fred/fred.ts +218 -0
- package/tutorial/fred/tutorial/01-introduction.md +141 -0
- package/tutorial/fred/tutorial/02-setup.md +304 -0
- package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
- package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
- package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
- package/tutorial/fred/tutorial/06-running-testing.md +642 -0
- package/tutorial/fred/tutorial/README.md +56 -0
- package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
- package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
- package/tutorial/full-guardrails-agent/handlers.ts +436 -0
- package/tutorial/full-guardrails-agent/penny.ts +305 -0
- package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
- package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
- package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
- package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
- package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
- package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
- package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
- package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
- package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
- package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
- package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
- package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
- package/tutorial/full-guardrails-agent/workflow.ts +219 -0
- package/tutorial/multi_agents/README.md +175 -0
- package/tutorial/multi_agents/advanced_agent.ts +395 -0
- package/tutorial/multi_agents/extending_agents.ts +641 -0
- package/tutorial/multi_agents/knowledge.ts +59 -0
- package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
- package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
- package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
- package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
- package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
- package/tutorial/multi_agents/pc_builder.ts +529 -0
- package/tutorial/multi_agents/sales_agent.ts +88 -0
- package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
- package/tutorial/multi_agents/sales_knowledge.md +139 -0
- package/tutorial/multi_agents/support_knowledge.md +256 -0
- package/dist/cli/mock-data.d.ts +0 -37
- package/dist/cli/mock-data.js +0 -80
- package/dist/cli/mock-data.js.map +0 -1
- package/dist/generateVerbTypes.d.ts +0 -11
- package/dist/generateVerbTypes.js +0 -265
- package/dist/generateVerbTypes.js.map +0 -1
- package/dist/rest/namespaces/compat.d.ts +0 -585
- package/dist/rest/namespaces/compat.js +0 -735
- package/dist/rest/namespaces/compat.js.map +0 -1
package/docs/security.md
ADDED
|
@@ -0,0 +1,559 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
<!-- snippet-setup -->
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
export {}; // treat each example as a module (top-level await)
|
|
7
|
+
declare global {
|
|
8
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
9
|
+
const AgentBase: typeof import('@signalwire/sdk').AgentBase; // used with `extends`
|
|
10
|
+
const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
|
|
11
|
+
const SslConfig: typeof import('@signalwire/sdk').SslConfig;
|
|
12
|
+
const SessionManager: typeof import('@signalwire/sdk').SessionManager;
|
|
13
|
+
const ssl: import('@signalwire/sdk').SslConfig;
|
|
14
|
+
const Hono: any; // Hono framework
|
|
15
|
+
const auth: any; // AuthHandler instance
|
|
16
|
+
const app: any; // Hono app
|
|
17
|
+
const cors: any; // Hono cors middleware
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
This page describes what the TypeScript SDK does to protect an agent's HTTP endpoints, what each setting changes, and what it leaves unprotected.
|
|
22
|
+
|
|
23
|
+
## Table of Contents
|
|
24
|
+
|
|
25
|
+
- [Overview](#overview)
|
|
26
|
+
- [Authentication](#authentication)
|
|
27
|
+
- [Webhook Signature Validation](#webhook-signature-validation)
|
|
28
|
+
- [Secure Tools (HMAC Tokens)](#secure-tools-hmac-tokens)
|
|
29
|
+
- [SSL/TLS](#ssltls)
|
|
30
|
+
- [Security Headers](#security-headers)
|
|
31
|
+
- [CORS](#cors)
|
|
32
|
+
- [CSRF Protection](#csrf-protection)
|
|
33
|
+
- [Rate Limiting](#rate-limiting)
|
|
34
|
+
- [Host Validation](#host-validation)
|
|
35
|
+
- [Request Size Limits](#request-size-limits)
|
|
36
|
+
- [Outbound URL Protection (SSRF)](#outbound-url-protection-ssrf)
|
|
37
|
+
- [Production Checklist](#production-checklist)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Overview
|
|
42
|
+
|
|
43
|
+
An `AgentBase` app applies these protections to the routes it serves. The first three are always on; the others are opt-in through options or environment variables.
|
|
44
|
+
|
|
45
|
+
- **Basic auth**: every agent route except `/health` and `/ready` requires the agent's credentials.
|
|
46
|
+
- **Security headers**: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, `Referrer-Policy`, `Content-Security-Policy` and `Permissions-Policy` on the agent's responses.
|
|
47
|
+
- **Secure tools**: a tool is secure unless you pass `secure: false`, and a secure tool runs only with a valid per-call token.
|
|
48
|
+
- **Webhook signatures**: with a signing key set, POSTs to the SWML, SWAIG and post-prompt routes must carry SignalWire's signature.
|
|
49
|
+
- **CORS, CSRF, rate limiting, host validation and request size**: controlled by `SWML_CORS_ORIGINS`, `SWML_CSRF_PROTECTION`, `SWML_RATE_LIMIT`, `SWML_ALLOWED_HOSTS` and `SWML_MAX_REQUEST_SIZE`.
|
|
50
|
+
- **Outbound URL checks**: the SDK's own fetches of URLs a caller, the model or a skill's configuration supplies refuse private and internal addresses.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Authentication
|
|
55
|
+
|
|
56
|
+
### Basic Auth (Default)
|
|
57
|
+
|
|
58
|
+
Every `AgentBase` app requires HTTP basic auth on the SWML route (`/`), `/swaig`, `/post_prompt`, `/debug_events`, `/mcp`, the optional override routes and any routing-callback path. The `/health` and `/ready` routes need no credentials, so a request to them doesn't test your credentials.
|
|
59
|
+
|
|
60
|
+
The agent resolves its credentials in this order:
|
|
61
|
+
|
|
62
|
+
1. The `basicAuth: [user, password]` constructor option.
|
|
63
|
+
2. A config file's `security.auth.basic` (or `security.basicAuth`) section, when you pass `configFile`.
|
|
64
|
+
3. `SWML_BASIC_AUTH_PASSWORD` from the environment, with `SWML_BASIC_AUTH_USER` as the username. The username defaults to `signalwire` when only the password is set.
|
|
65
|
+
4. A generated password: 32 random hex characters, with `SWML_BASIC_AUTH_USER` or the agent's name as the username.
|
|
66
|
+
|
|
67
|
+
A generated password exists only in the running process, and the agent logs a `basic_auth_password_autogenerated` warning when it makes one. The startup log line shows the username and `****` in place of any password, so don't look for the password there:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
Auth: my-agent:**** (source: generated)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Set the credentials yourself for any agent SignalWire or another client calls. This example passes them to the constructor from environment variables your deployment defines, and refuses to start without them, so a missing variable can't leave a known password in place:
|
|
74
|
+
|
|
75
|
+
<!-- snippet: no-run throws by design unless AGENT_USER and AGENT_PASSWORD are set -->
|
|
76
|
+
|
|
77
|
+
```typescript
|
|
78
|
+
import { AgentBase } from '@signalwire/sdk';
|
|
79
|
+
|
|
80
|
+
const user = process.env.AGENT_USER;
|
|
81
|
+
const password = process.env.AGENT_PASSWORD;
|
|
82
|
+
if (!user || !password) throw new Error('Set AGENT_USER and AGENT_PASSWORD');
|
|
83
|
+
|
|
84
|
+
const agent = new AgentBase({ name: 'my-agent', basicAuth: [user, password] });
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
In code, `getBasicAuthCredentials()` returns the credentials in use, and `getBasicAuthCredentials(true)` adds where they came from:
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
const [user, pass] = agent.getBasicAuthCredentials();
|
|
91
|
+
const [user2, pass2, source] = agent.getBasicAuthCredentials(true);
|
|
92
|
+
// source: 'provided' | 'environment' | 'config file' | 'generated'
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The agent puts the credentials into the webhook URLs of the SWML it serves (`https://user:password@host/swaig?...`), so SignalWire can call back. Anyone who can read that SWML can read the password. The SWML route itself requires the credentials.
|
|
96
|
+
|
|
97
|
+
Every route that requires basic auth passes the request's credentials to `validateBasicAuth()`, which compares them with the configured pair in constant time. Override it to add a check of your own; an override replaces the comparison, so call `super.validateBasicAuth()` to keep it.
|
|
98
|
+
|
|
99
|
+
### AuthHandler (Multi-Method)
|
|
100
|
+
|
|
101
|
+
`AuthHandler` (`src/AuthHandler.ts`) is a standalone helper for your own Hono or Express routes. The agent's own routes don't use it. It accepts a bearer token, an API key header, basic auth credentials and a custom validator, and compares secrets in constant time:
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
import { AuthHandler } from '@signalwire/sdk';
|
|
105
|
+
|
|
106
|
+
const auth = new AuthHandler({
|
|
107
|
+
// Authorization: Bearer <token>
|
|
108
|
+
bearerToken: 'a-long-random-token',
|
|
109
|
+
|
|
110
|
+
// X-Api-Key: <key> (apiKeyHeader changes the header name)
|
|
111
|
+
apiKey: 'a-long-random-key',
|
|
112
|
+
|
|
113
|
+
// Authorization: Basic <base64 of user:password>
|
|
114
|
+
basicAuth: ['admin', 'a-long-random-password'],
|
|
115
|
+
|
|
116
|
+
// Receives the headers; method and url are passed as empty strings
|
|
117
|
+
customValidator: async (req) => req.headers['x-internal-service'] === 'trusted',
|
|
118
|
+
|
|
119
|
+
// Deny every request when no method is configured
|
|
120
|
+
allowUnauthenticated: false,
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`validate()` tries the configured methods in order (bearer token, API key, basic auth, custom validator) and allows the request when one of them matches. With no method configured, it allows every request and logs a warning, unless `allowUnauthenticated` is `false`.
|
|
125
|
+
|
|
126
|
+
`middleware()` returns Hono middleware that answers a failed check with `401` and `{ "error": "Unauthorized" }`. `expressMiddleware()` does the same for Express-style apps. This fragment protects the routes under `/api/`:
|
|
127
|
+
|
|
128
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `Hono` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
const app = new Hono();
|
|
132
|
+
app.use('/api/*', auth.middleware());
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Webhook Signature Validation
|
|
138
|
+
|
|
139
|
+
SignalWire signs the webhooks it sends with the Signing Key from your space's API credentials. With the key set, the agent checks each signature before it runs the handler. Without it, anyone who has the basic auth credentials can send the agent a request that looks like SignalWire's.
|
|
140
|
+
|
|
141
|
+
### Enabling Validation
|
|
142
|
+
|
|
143
|
+
Pass `signingKey` to the constructor, or set `SIGNALWIRE_SIGNING_KEY`. The option wins when both are set:
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
import { AgentBase } from '@signalwire/sdk';
|
|
147
|
+
|
|
148
|
+
const agent = new AgentBase({
|
|
149
|
+
name: 'my-agent',
|
|
150
|
+
signingKey: process.env.SIGNALWIRE_SIGNING_KEY,
|
|
151
|
+
webhookTrustProxy: false, // set true only when you control every proxy in front of the agent
|
|
152
|
+
});
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
When neither is set, the agent logs this warning when it's created:
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
[signalwire] webhook signature validation is disabled — set signingKey or SIGNALWIRE_SIGNING_KEY to enable
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
The resolved key is readable as `agent.signingKey`, which is `null` when validation is off. The SDK doesn't log it or put it in the SWML.
|
|
162
|
+
|
|
163
|
+
### Routes That Check It
|
|
164
|
+
|
|
165
|
+
With a key set, the agent checks the signature on POST requests to these routes, after basic auth:
|
|
166
|
+
|
|
167
|
+
- The SWML route (`/`), with and without a trailing slash
|
|
168
|
+
- `/swaig`
|
|
169
|
+
- `/post_prompt`
|
|
170
|
+
- Every routing-callback path, since it renders SWML like the root
|
|
171
|
+
|
|
172
|
+
A request with a missing or wrong signature gets `403` with the body `Forbidden`, and the handler doesn't run. The check applies however the app is served: `serve()`, `getApp()`, `asRouter()`, `AgentServer`, or a serverless adapter.
|
|
173
|
+
|
|
174
|
+
These requests aren't checked: GET requests to any route, `/mcp` (MCP clients don't sign requests), `/debug_events`, `/post_prompt_override`, `/check_for_input`, `/health` and `/ready`. `SWMLService` has no signature check.
|
|
175
|
+
|
|
176
|
+
### What Is Signed
|
|
177
|
+
|
|
178
|
+
The agent accepts either of two headers:
|
|
179
|
+
|
|
180
|
+
- `X-SignalWire-Sha256-Signature`: the lowercase hex HMAC-SHA256 of the URL followed by the raw body. The agent checks it first when it's present.
|
|
181
|
+
- `X-SignalWire-Signature`: the SHA-1 signature. It decides when the SHA-256 header is missing or doesn't match. `X-Twilio-Signature` is accepted in its place for cXML compatibility.
|
|
182
|
+
|
|
183
|
+
The SHA-1 header can carry either of two schemes, and the validator tries both:
|
|
184
|
+
|
|
185
|
+
- **JSON requests** (SWML, SWAIG, post-prompt): `hex(HMAC-SHA1(key, url + rawBody))`.
|
|
186
|
+
- **Form-encoded requests** (cXML): the base64 HMAC-SHA1 of the URL followed by each form parameter's name and value, sorted by name. The validator tries the URL with and without the default port (`:443` or `:80`). When the URL carries a `bodySHA256` query parameter, the SHA-256 hex digest of the body must equal it.
|
|
187
|
+
|
|
188
|
+
`url` is the full URL SignalWire requested: scheme, host, any non-standard port, path and query string. `rawBody` is the body as it arrived, before JSON parsing. The middleware reads the raw body itself, before any parser, and leaves it in the Hono context as `c.get('rawBody')`.
|
|
189
|
+
|
|
190
|
+
These test vectors come from the Python SDK's documentation, and the TypeScript validators accept them:
|
|
191
|
+
|
|
192
|
+
| Scheme | Signing key | URL | Body | Signature |
|
|
193
|
+
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
|
|
194
|
+
| JSON, SHA-1 | `PSKtest1234567890abcdef` | `https://example.ngrok.io/webhook` | `{"event":"call.state","params":{"call_id":"abc-123","state":"answered"}}` | `c3c08c1fefaf9ee198a100d5906765a6f394bf0f` |
|
|
195
|
+
| Form | `12345` | `https://mycompany.com/myapp.php?foo=1&bar=2` | `CallSid=CA1234567890ABCDE`, `Caller=+14158675309`, `Digits=1234`, `From=+14158675309`, `To=+18005551212` | `RSOYDt4T1cUTdK1PDd93/VVr8B8=` |
|
|
196
|
+
| JSON on a form endpoint | `PSKtest1234567890abcdef` | `https://example.ngrok.io/webhook?bodySHA256=69f3cbfc18e386ef8236cb7008cd5a54b7fed637a8cb3373b5a1591d7f0fd5f4` | `{"event":"call.state"}` | `dfO9ek8mxyFtn2nMz24plPmPfIY=` |
|
|
197
|
+
|
|
198
|
+
`validateWebhookSignature()` accepts the first and third rows, and `validateRequest()` accepts the second, with the form parameters passed as an object. For the first row's URL and body, `validateWebhookSignatureSha256()` accepts `2a29f8a92b11df39da80c3b185fd62173d49c294184da585ff951eae4433571c`.
|
|
199
|
+
|
|
200
|
+
### URL Reconstruction Behind a Proxy
|
|
201
|
+
|
|
202
|
+
The signature covers the URL SignalWire requested, which differs from the URL the agent sees behind a reverse proxy or tunnel. The middleware rebuilds it in this order:
|
|
203
|
+
|
|
204
|
+
1. `SWML_PROXY_URL_BASE`, joined with the request's path and query.
|
|
205
|
+
2. `X-Forwarded-Proto` and `X-Forwarded-Host`, only when `webhookTrustProxy` is `true`. The protocol defaults to `https`.
|
|
206
|
+
3. The URL the request arrived on.
|
|
207
|
+
|
|
208
|
+
Forwarded headers are easy to forge, so turn on `webhookTrustProxy` only when you control every proxy in front of the agent. `SWML_TRUST_PROXY_HEADERS` is a separate setting: it lets the agent build its webhook URLs and rate-limit keys from forwarded headers, and it doesn't affect the signature check.
|
|
209
|
+
|
|
210
|
+
On a serverless platform, the adapter passes the URL the platform received the request on, so the signature is checked against that URL. The [Serverless Guide](serverless-guide.md#webhook-urls-and-signatures) covers each platform. If signed requests are refused with `403`, set `SWML_PROXY_URL_BASE` to the public base URL SignalWire calls.
|
|
211
|
+
|
|
212
|
+
### Validating in Your Own App
|
|
213
|
+
|
|
214
|
+
Outside `AgentBase`, use `webhookValidationMiddleware()` on your Hono routes. It takes the same `signingKey` and `trustProxy` options, and throws at construction when the key is empty:
|
|
215
|
+
|
|
216
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `Hono` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
217
|
+
|
|
218
|
+
```typescript
|
|
219
|
+
import { webhookValidationMiddleware } from '@signalwire/sdk';
|
|
220
|
+
|
|
221
|
+
const app = new Hono();
|
|
222
|
+
app.use(
|
|
223
|
+
'/webhook',
|
|
224
|
+
webhookValidationMiddleware({ signingKey: process.env.SIGNALWIRE_SIGNING_KEY! }),
|
|
225
|
+
);
|
|
226
|
+
app.post('/webhook', (c: any) => c.json({ received: c.get('rawBody') }));
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
For other frameworks, `validate(method, url, headers, rawBody, signingKey)` returns `null` for an authentic request, or a `[403, {}, 'Forbidden']` triple to send back. The lower-level `validateWebhookSignature()`, `validateWebhookSignatureSha256()` and `validateRequest()` return a boolean. All of them throw when the signing key is empty.
|
|
230
|
+
|
|
231
|
+
### What a Signature Doesn't Cover
|
|
232
|
+
|
|
233
|
+
The signature has no timestamp, so it doesn't stop a captured request from being sent again. Make side effects idempotent. The per-call tool tokens described in [Secure Tools (HMAC Tokens)](#secure-tools-hmac-tokens) limit a replayed tool call to the same call and tool, until the token expires. The signature also doesn't cover the HTTP method or the headers.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Secure Tools (HMAC Tokens)
|
|
238
|
+
|
|
239
|
+
`SessionManager` (`src/SessionManager.ts`) signs a token for each secure tool in each call, so a tool's URL can't be reused for another call or another tool.
|
|
240
|
+
|
|
241
|
+
### How It Works
|
|
242
|
+
|
|
243
|
+
A tool is secure unless you pass `secure: false` to `defineTool()`. These steps connect a secure tool's token to the call:
|
|
244
|
+
|
|
245
|
+
1. SignalWire requests the SWML for a call with a POST whose body carries the `call_id`. For a GET, the agent reads `?call_id=` from the query.
|
|
246
|
+
2. The agent signs a token for each secure tool and that `call_id`, and appends it to the tool's `web_hook_url` as `__token`.
|
|
247
|
+
3. When `/swaig` receives a call to a secure tool, the agent checks the token against the function name and the `call_id` in the request body.
|
|
248
|
+
|
|
249
|
+
A missing token, a missing `call_id` or an invalid token gets the same refusal, returned as the tool's response with HTTP `200`:
|
|
250
|
+
|
|
251
|
+
```json
|
|
252
|
+
{
|
|
253
|
+
"response": "I'm sorry, the security token for this function is invalid or expired. I cannot execute this action."
|
|
254
|
+
}
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
The handler doesn't run. A tool with `secure: false` runs for anyone who has the basic auth credentials. With a dynamic config callback or `addPerCallConfig()`, the agent checks the token on the per-request copy. A secure tool that the callback registers needs its token too.
|
|
258
|
+
|
|
259
|
+
This example registers a tool that moves money, so it keeps the default and runs only with its call's token:
|
|
260
|
+
|
|
261
|
+
```typescript
|
|
262
|
+
agent.defineTool({
|
|
263
|
+
name: 'transfer_funds',
|
|
264
|
+
description: 'Transfer money between accounts',
|
|
265
|
+
parameters: {
|
|
266
|
+
type: 'object',
|
|
267
|
+
properties: {
|
|
268
|
+
amount: { type: 'number', description: 'Amount to transfer' },
|
|
269
|
+
toAccount: { type: 'string', description: 'Destination account ID' },
|
|
270
|
+
},
|
|
271
|
+
},
|
|
272
|
+
secure: true, // the default; shown for clarity
|
|
273
|
+
handler: async (args, rawData) => {
|
|
274
|
+
// Runs only with a valid, unexpired token for this call
|
|
275
|
+
return new FunctionResult('Transfer completed.');
|
|
276
|
+
},
|
|
277
|
+
});
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
To call a secure tool by hand, request the SWML with `?call_id=<id>` and take the tool's `web_hook_url` from it. Then POST to that URL with the same `call_id` in the body. `swaig-test` does this for you: it requests the SWML and calls each function at the URL the SWML gives it, token included.
|
|
281
|
+
|
|
282
|
+
### Token Format
|
|
283
|
+
|
|
284
|
+
A token is the base64url encoding of five dot-separated fields:
|
|
285
|
+
|
|
286
|
+
```text
|
|
287
|
+
base64url( callId.functionName.expiry.nonce.signature )
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
| Field | Description |
|
|
291
|
+
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
292
|
+
| `callId` | The call the token is bound to. It may itself contain dots (a composed ID such as `root.2`), so the other four fields are read from the right. |
|
|
293
|
+
| `functionName` | The tool the token authorizes. |
|
|
294
|
+
| `expiry` | Unix time in seconds when the token stops being valid. |
|
|
295
|
+
| `nonce` | 16 random hex characters. |
|
|
296
|
+
| `signature` | The full 64-character hex HMAC-SHA256 of `callId:functionName:expiry:nonce`, compared in constant time. |
|
|
297
|
+
|
|
298
|
+
### Token Lifetime
|
|
299
|
+
|
|
300
|
+
`AgentBase` signs tokens that last 3600 seconds (one hour) by default. A token is signed when the SWML is rendered at the start of the call, so a tool called later than the expiry is refused. Set `tokenExpirySecs` longer than your longest call:
|
|
301
|
+
|
|
302
|
+
```typescript
|
|
303
|
+
const agent = new AgentBase({
|
|
304
|
+
name: 'my-agent',
|
|
305
|
+
tokenExpirySecs: 7200, // 2 hours
|
|
306
|
+
});
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
A `SessionManager` you construct yourself defaults to 900 seconds.
|
|
310
|
+
|
|
311
|
+
### The Signing Secret
|
|
312
|
+
|
|
313
|
+
The agent signs tokens with the first secret it finds: the `swaigSecret` option, then `SIGNALWIRE_SWAIG_SECRET`, then 32 random bytes generated at startup.
|
|
314
|
+
|
|
315
|
+
With the generated secret, tokens stop validating when the agent restarts, and each replica of the same agent signs with a different key. A call that started before a restart, or whose next request reaches another replica, gets the refusal shown earlier. The failure reads as a tool error, and the server logs only a `token_invalid` warning.
|
|
316
|
+
|
|
317
|
+
Set the secret whenever the agent restarts while calls are live (every rolling deploy does this) and whenever more than one replica serves the agent. Use the same value on every replica, and keep it out of source control:
|
|
318
|
+
|
|
319
|
+
```typescript
|
|
320
|
+
const agent = new AgentBase({
|
|
321
|
+
name: 'my-agent',
|
|
322
|
+
swaigSecret: process.env.SIGNALWIRE_SWAIG_SECRET,
|
|
323
|
+
});
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
This secret belongs to the agent and never leaves the process. It's unrelated to the signing key, which SignalWire issues and uses to sign requests to the agent.
|
|
327
|
+
|
|
328
|
+
### The Post-Prompt Token
|
|
329
|
+
|
|
330
|
+
The post-prompt URL in the SWML carries a token for its call too, signed for the name `post_prompt`. The agent refuses a summary POSTed to `/post_prompt` without a valid token with `403` and `{"error": "Invalid or missing token"}`. When the URL's `call_id` and the body's `call_id` differ, it answers `400`, so a token for one call can't deliver another call's summary.
|
|
331
|
+
|
|
332
|
+
### Debugging Tokens
|
|
333
|
+
|
|
334
|
+
`debugToken()` decodes a token without validating it, for troubleshooting. It works only when you set `debugMode`, and it shortens the call ID and signature in its output:
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
import { SessionManager } from '@signalwire/sdk';
|
|
338
|
+
|
|
339
|
+
const sm = new SessionManager(3600);
|
|
340
|
+
sm.debugMode = true;
|
|
341
|
+
const token = sm.generateToken('my_function', 'call-123');
|
|
342
|
+
const info = sm.debugToken(token);
|
|
343
|
+
console.log(info.components?.function, info.status?.is_expired);
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
### Session Metadata
|
|
347
|
+
|
|
348
|
+
`SessionManager` also stores metadata per session in memory. It isn't shared between processes, and entries older than the token lifetime are removed when the store passes 1000 sessions:
|
|
349
|
+
|
|
350
|
+
```typescript
|
|
351
|
+
const sm = new SessionManager();
|
|
352
|
+
|
|
353
|
+
sm.setSessionMetadata('session-1', { userId: 'u-42', plan: 'pro' });
|
|
354
|
+
const meta = sm.getSessionMetadata('session-1'); // { userId: 'u-42', plan: 'pro' }
|
|
355
|
+
|
|
356
|
+
sm.deleteSessionMetadata('session-1');
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
---
|
|
360
|
+
|
|
361
|
+
## SSL/TLS
|
|
362
|
+
|
|
363
|
+
`AgentBase.serve()` and `AgentServer.run()` serve HTTPS when `SWML_SSL_ENABLED` is `true`, `1` or `yes` and `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH` name the certificate and key; otherwise they serve plain HTTP. The agent's webhook URLs then use `https`, on `SWML_SSL_DOMAIN` when it's set. You can also terminate TLS at a reverse proxy or load balancer; then set `SWML_PROXY_URL_BASE` to the agent's public `https://` URL so its webhook URLs use it.
|
|
364
|
+
|
|
365
|
+
`SslConfig` (`src/SslConfig.ts`) holds the certificate settings the agents, `SWMLService.serve()` and `WebService` use to serve HTTPS, and that your own servers can use. It reads these variables when you don't pass the matching option:
|
|
366
|
+
|
|
367
|
+
| Variable | Description |
|
|
368
|
+
| -------------------- | ----------------------------------------- |
|
|
369
|
+
| `SWML_SSL_ENABLED` | `true` enables SSL. |
|
|
370
|
+
| `SWML_SSL_CERT_PATH` | Path to the PEM-encoded certificate file. |
|
|
371
|
+
| `SWML_SSL_KEY_PATH` | Path to the PEM-encoded private key file. |
|
|
372
|
+
| `SWML_SSL_DOMAIN` | Domain name for HSTS. |
|
|
373
|
+
|
|
374
|
+
This example builds the configuration from options:
|
|
375
|
+
|
|
376
|
+
```typescript
|
|
377
|
+
import { SslConfig } from '@signalwire/sdk';
|
|
378
|
+
|
|
379
|
+
const ssl = new SslConfig({
|
|
380
|
+
enabled: true,
|
|
381
|
+
certPath: '/etc/ssl/certs/agent.pem',
|
|
382
|
+
keyPath: '/etc/ssl/private/agent-key.pem',
|
|
383
|
+
domain: 'agent.example.com',
|
|
384
|
+
hsts: true, // default: true
|
|
385
|
+
hstsMaxAge: 31536000, // default: 31536000 (1 year)
|
|
386
|
+
});
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### SslOptions Interface
|
|
390
|
+
|
|
391
|
+
| Property | Type | Default | Description |
|
|
392
|
+
| ------------ | --------- | ---------- | --------------------------------- |
|
|
393
|
+
| `enabled` | `boolean` | `false` | Whether SSL is enabled. |
|
|
394
|
+
| `certPath` | `string` | none | Path to the PEM certificate file. |
|
|
395
|
+
| `keyPath` | `string` | none | Path to the PEM private key file. |
|
|
396
|
+
| `domain` | `string` | none | Domain name for HSTS. |
|
|
397
|
+
| `hsts` | `boolean` | `true` | Whether to emit HSTS headers. |
|
|
398
|
+
| `hstsMaxAge` | `number` | `31536000` | HSTS `max-age` value in seconds. |
|
|
399
|
+
|
|
400
|
+
### Using SslConfig
|
|
401
|
+
|
|
402
|
+
`isConfigured()` is true when SSL is enabled and both files exist. `getServerOptions()` reads them for `https.createServer()`, and `getHstsHeader()` returns the header value, or `null` when HSTS or SSL is off:
|
|
403
|
+
|
|
404
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `ssl` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
405
|
+
|
|
406
|
+
```typescript
|
|
407
|
+
if (ssl.isConfigured()) {
|
|
408
|
+
const serverOpts = ssl.getServerOptions(); // { cert: '...', key: '...' }
|
|
409
|
+
}
|
|
410
|
+
const hsts = ssl.getHstsHeader(); // "max-age=31536000; includeSubDomains"
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
The agent doesn't send `Strict-Transport-Security`. To add it to your own Hono app, use `hstsMiddleware()`:
|
|
414
|
+
|
|
415
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `app` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
416
|
+
|
|
417
|
+
```typescript
|
|
418
|
+
app.use('*', ssl.hstsMiddleware());
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
### Custom CA Certificates for Outbound TLS
|
|
422
|
+
|
|
423
|
+
Two variables set the certificate authorities the SDK trusts when it connects to SignalWire. `SIGNALWIRE_REST_CA_FILE` applies to the REST client (`HttpClient`), and `SIGNALWIRE_RELAY_CA_FILE` to the RELAY WebSocket (`RelayClient`). Each names a PEM bundle, for example for a private CA or a TLS-inspecting proxy.
|
|
424
|
+
|
|
425
|
+
The bundle replaces Node's default trust store for that connection, so it must contain every CA the server's certificate can chain to. Neither setting disables certificate verification. When a variable is unset, or its file can't be read, the connection uses Node's default trust store.
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
## Security Headers
|
|
430
|
+
|
|
431
|
+
`AgentBase` and `AgentServer` set these headers on the responses of the agent's own routes:
|
|
432
|
+
|
|
433
|
+
| Header | Value |
|
|
434
|
+
| ------------------------- | -------------------------------------------- |
|
|
435
|
+
| `X-Content-Type-Options` | `nosniff` |
|
|
436
|
+
| `X-Frame-Options` | `DENY` |
|
|
437
|
+
| `X-XSS-Protection` | `1; mode=block` |
|
|
438
|
+
| `Referrer-Policy` | `strict-origin-when-cross-origin` |
|
|
439
|
+
| `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` |
|
|
440
|
+
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |
|
|
441
|
+
|
|
442
|
+
They need no configuration. An app you add with `mount()` keeps its own headers, since a page couldn't load under `default-src 'none'`.
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
## CORS
|
|
447
|
+
|
|
448
|
+
When `SWML_CORS_ORIGINS` is unset, the agent's CORS policy allows any origin (`Access-Control-Allow-Origin: *`) without credentials. Set it to a comma-separated list of origins to allow only those:
|
|
449
|
+
|
|
450
|
+
```bash
|
|
451
|
+
export SWML_CORS_ORIGINS="https://app.example.com,https://admin.example.com"
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
With the list set, a listed origin gets CORS headers with `Access-Control-Allow-Credentials: true`, and other origins get none, so browsers block their cross-origin requests. A list that holds `*`, or an unset variable, allows any origin, without credentials. `AgentServer` reads the same variable.
|
|
455
|
+
|
|
456
|
+
---
|
|
457
|
+
|
|
458
|
+
## CSRF Protection
|
|
459
|
+
|
|
460
|
+
Set `SWML_CSRF_PROTECTION=true` to refuse POST requests from browser origins you haven't listed. The check uses the `SWML_CORS_ORIGINS` list:
|
|
461
|
+
|
|
462
|
+
```bash
|
|
463
|
+
export SWML_CORS_ORIGINS="https://app.example.com"
|
|
464
|
+
export SWML_CSRF_PROTECTION=true
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
A POST whose `Origin` header isn't in the list gets `403` and `{ "error": "Origin not allowed" }`. A request without an `Origin` header passes, as SignalWire's requests do. When `SWML_CORS_ORIGINS` is unset, the check refuses nothing.
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Rate Limiting
|
|
472
|
+
|
|
473
|
+
Set `SWML_RATE_LIMIT` to a positive number of requests per minute to limit request rates:
|
|
474
|
+
|
|
475
|
+
```bash
|
|
476
|
+
export SWML_RATE_LIMIT=120
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
The limit applies per client key, and the counter for a key resets 60 seconds after its first request. A request over the limit gets `429` and `{ "error": "Rate limit exceeded" }`. Every route counts, `/health` and `/ready` included.
|
|
480
|
+
|
|
481
|
+
The client key depends on `SWML_TRUST_PROXY_HEADERS`:
|
|
482
|
+
|
|
483
|
+
- **Unset**: the key is the address of the connection, or on a serverless platform the client address the platform reports (Lambda's source IP, a Cloud Function request's `ip`, CGI's `REMOTE_ADDR`). Azure Functions reports none, so its requests share one key. Behind a proxy, the key is the proxy's address, so every client behind it shares one key.
|
|
484
|
+
- **`true`**: the key is the first address in `X-Forwarded-For`, then `X-Real-IP`, then the connection's address. Set this only behind a proxy that sets those headers, since a client can send any value.
|
|
485
|
+
|
|
486
|
+
Size the limit for the traffic one key sends, including SignalWire's requests during calls. When `SWML_RATE_LIMIT` is unset, no limit applies.
|
|
487
|
+
|
|
488
|
+
---
|
|
489
|
+
|
|
490
|
+
## Host Validation
|
|
491
|
+
|
|
492
|
+
Set `SWML_ALLOWED_HOSTS` to a comma-separated list of host names the agent answers to:
|
|
493
|
+
|
|
494
|
+
```bash
|
|
495
|
+
export SWML_ALLOWED_HOSTS="agent.example.com,api.example.com"
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
The agent strips the port from the `Host` header and compares the rest, ignoring case, with the list. A request for another host gets `403` and `{ "error": "Forbidden: host not allowed" }`, on every route including `/health`. A list that holds `*`, or an unset variable, accepts any host. There are no partial wildcards such as `*.example.com`.
|
|
499
|
+
|
|
500
|
+
The check blocks requests that reach the agent by IP address or through a DNS name you didn't list, as in DNS rebinding.
|
|
501
|
+
|
|
502
|
+
---
|
|
503
|
+
|
|
504
|
+
## Request Size Limits
|
|
505
|
+
|
|
506
|
+
The agent refuses a request whose `Content-Length` header exceeds `SWML_MAX_REQUEST_SIZE` bytes, with `413` and `{ "error": "Request too large" }`. The default is 1048576 bytes (1 MB):
|
|
507
|
+
|
|
508
|
+
```bash
|
|
509
|
+
# Limit to 512 KB
|
|
510
|
+
export SWML_MAX_REQUEST_SIZE=524288
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
The check reads only the header. A request without `Content-Length`, such as a chunked upload, isn't limited by it, so enforce a body limit at your proxy as well.
|
|
514
|
+
|
|
515
|
+
---
|
|
516
|
+
|
|
517
|
+
## Outbound URL Protection (SSRF)
|
|
518
|
+
|
|
519
|
+
Some SDK features fetch URLs that a caller, the model or a skill's configuration supplies. To keep those fetches away from internal services, the SDK refuses a URL that isn't `http` or `https`. It also refuses a host that can't be resolved, or that resolves to any address in these ranges:
|
|
520
|
+
|
|
521
|
+
- IPv4 private networks: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
|
|
522
|
+
- Loopback and unspecified: `127.0.0.0/8`, `0.0.0.0/8`, `::1`, `::`
|
|
523
|
+
- Link-local, including cloud metadata services: `169.254.0.0/16`, `fe80::/10`
|
|
524
|
+
- IPv6 unique local: `fc00::/7`
|
|
525
|
+
- IPv4-mapped IPv6 addresses (`::ffff:169.254.169.254`), checked as the IPv4 address they carry
|
|
526
|
+
|
|
527
|
+
The `web_search` and `spider` skills, and the `swaig-test` DataMap simulator, fetch pages through a guarded client. It checks the URL and every redirect before requesting it: up to 10 redirects for the skills, and up to 15 for the simulator, which follows them as the platform's curl does and sends a `POST` again with its body. It connects only to an address it checked, which also stops DNS rebinding. A redirect to another origin drops the `Authorization`, `Cookie` and `Proxy-Authorization` headers. The `mcp_gateway` skill and `native_vector_search` in remote mode send every request to `gateway_url` or `remote_url` through the same client. With `allow_insecure_tls` on, `mcp_gateway` still uses this client, which then skips only the certificate check.
|
|
528
|
+
|
|
529
|
+
Two variables change this behavior:
|
|
530
|
+
|
|
531
|
+
- `SWML_ALLOW_PRIVATE_URLS=true` (or `1`, `yes`) turns the address checks off. Use it only when an agent must reach a service on a private network, such as a gateway on `localhost` in development.
|
|
532
|
+
- `SWML_URL_FETCH_USE_PROXY=true` (or `1`, `yes`) lets the guarded client use the environment's proxy when Node would use one. Node uses a proxy when `NODE_USE_ENV_PROXY` or `--use-env-proxy` is set, `HTTPS_PROXY` or `HTTP_PROXY` names one, and `NO_PROXY` doesn't exclude the host. The address check can't apply to a proxied connection, so use a proxy that restricts destinations itself.
|
|
533
|
+
|
|
534
|
+
These checks cover the SDK's own fetches. They don't cover `fetch()` calls in your tool handlers, or DataMap webhooks, which SignalWire makes. To check a URL in your own code, call `validateUrl()`, which resolves the host and returns `false` for a URL the SDK would refuse:
|
|
535
|
+
|
|
536
|
+
```typescript
|
|
537
|
+
import { validateUrl } from '@signalwire/sdk';
|
|
538
|
+
|
|
539
|
+
console.log(await validateUrl('http://169.254.169.254/latest/meta-data/')); // false
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
---
|
|
543
|
+
|
|
544
|
+
## Production Checklist
|
|
545
|
+
|
|
546
|
+
Check these settings before an agent takes production traffic:
|
|
547
|
+
|
|
548
|
+
- [ ] Set basic auth credentials with `basicAuth` or `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD`. A generated password exists only in one process, and SignalWire can't use it after a restart.
|
|
549
|
+
- [ ] Set `signingKey` or `SIGNALWIRE_SIGNING_KEY` so the agent checks SignalWire's signatures. If the agent is behind a proxy or tunnel, set `SWML_PROXY_URL_BASE` to its public URL.
|
|
550
|
+
- [ ] Set `swaigSecret` or `SIGNALWIRE_SWAIG_SECRET`, with the same value on every replica, so tool tokens survive restarts and work across replicas.
|
|
551
|
+
- [ ] Set `tokenExpirySecs` longer than your longest call.
|
|
552
|
+
- [ ] Keep `secure` on (the default) for every tool that reads or changes private data, moves money, or controls the call.
|
|
553
|
+
- [ ] Terminate TLS in front of the agent, and set `SWML_PROXY_URL_BASE` to the `https://` URL SignalWire should call.
|
|
554
|
+
- [ ] Set `SWML_ALLOWED_HOSTS` to the host names the agent serves.
|
|
555
|
+
- [ ] Set `SWML_CORS_ORIGINS` if a browser app calls the agent, and add `SWML_CSRF_PROTECTION=true`.
|
|
556
|
+
- [ ] If you set `SWML_RATE_LIMIT`, size it for the agent's total traffic, or set `SWML_TRUST_PROXY_HEADERS=true` behind a proxy that sets `X-Forwarded-For`.
|
|
557
|
+
- [ ] Leave `SWML_ALLOW_PRIVATE_URLS` unset unless the agent must reach a private service.
|
|
558
|
+
- [ ] Set `SIGNALWIRE_LOG_LEVEL=warn` or `error` if debug logs would record call data you don't want kept.
|
|
559
|
+
- [ ] Point load balancer health checks at `/health` or `/ready`, which need no credentials.
|