@wildo-ai/saas-backend-lib 1.1.3 → 1.1.4

package/dist/esm/notifications/sms/models/sms-transport.backend.definitions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hard deadline for one external SMS-provider request, including response body consumption.
+ *
+ * ## Why this is NOT `EMAIL_PROVIDER_TRANSPORT_TIMEOUT_MS` (60s)
+ *
+ * The bound is a statement about how long the work legitimately takes and about who is waiting,
+ * not a house style — which is why this package already carries a measured spread rather than one
+ * number: 5s for a CIMD document fetched on behalf of an unauthenticated stranger, 10s for OIDC
+ * discovery, 15s for an STS credential, 60s for an email submission or a virus scan, 120s for
+ * document extraction, and a per-binding value for ETL and MCP.
+ *
+ * Two things separate SMS from email, and they push in the same direction:
+ *
+ * 1. **The payload.** An email submission can carry attachments up to
+ *    `OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT`, so 60s is time spent moving bytes the provider has to
+ *    accept. An SMS submission is one short form- or JSON-encoded POST whose body is bounded by the
+ *    message itself. There is no payload for the extra 45s to serve.
+ * 2. **Who is blocked.** Email send is a recoverable job behind a durable lease — nobody is sitting
+ *    in front of it, which is what makes a generous bound affordable there. The SMS path is reached
+ *    SYNCHRONOUSLY from phone verification and the SMS second factor, so this deadline is the upper
+ *    bound on how long a human stares at a sign-in form while an unresponsive vendor holds a socket
+ *    open. That is the failure this constant exists to cap.
+ *
+ * 15s is therefore sized by the person waiting rather than by the bytes, and is still several times
+ * the observed round trip of an SMS submission API.
+ *
+ * The deadline covers response-body consumption as well as receipt of headers. A provider that
+ * answers headers and then stalls its body retains the request exactly as effectively as one that
+ * never answers at all, so a bound that stops at the headers is not a bound.
+ */
+export declare const SMS_PROVIDER_TRANSPORT_TIMEOUT_MS = 15000;
+//# sourceMappingURL=sms-transport.backend.definitions.d.ts.map

package/dist/esm/notifications/sms/models/sms-transport.backend.definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sms-transport.backend.definitions.d.ts","sourceRoot":"","sources":["../../../../../src/notifications/sms/models/sms-transport.backend.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iCAAiC,QAAS,CAAC"}

package/dist/esm/notifications/sms/models/sms-transport.backend.definitions.js

@@ -0,0 +1,32 @@
+/**
+ * Hard deadline for one external SMS-provider request, including response body consumption.
+ *
+ * ## Why this is NOT `EMAIL_PROVIDER_TRANSPORT_TIMEOUT_MS` (60s)
+ *
+ * The bound is a statement about how long the work legitimately takes and about who is waiting,
+ * not a house style — which is why this package already carries a measured spread rather than one
+ * number: 5s for a CIMD document fetched on behalf of an unauthenticated stranger, 10s for OIDC
+ * discovery, 15s for an STS credential, 60s for an email submission or a virus scan, 120s for
+ * document extraction, and a per-binding value for ETL and MCP.
+ *
+ * Two things separate SMS from email, and they push in the same direction:
+ *
+ * 1. **The payload.** An email submission can carry attachments up to
+ *    `OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT`, so 60s is time spent moving bytes the provider has to
+ *    accept. An SMS submission is one short form- or JSON-encoded POST whose body is bounded by the
+ *    message itself. There is no payload for the extra 45s to serve.
+ * 2. **Who is blocked.** Email send is a recoverable job behind a durable lease — nobody is sitting
+ *    in front of it, which is what makes a generous bound affordable there. The SMS path is reached
+ *    SYNCHRONOUSLY from phone verification and the SMS second factor, so this deadline is the upper
+ *    bound on how long a human stares at a sign-in form while an unresponsive vendor holds a socket
+ *    open. That is the failure this constant exists to cap.
+ *
+ * 15s is therefore sized by the person waiting rather than by the bytes, and is still several times
+ * the observed round trip of an SMS submission API.
+ *
+ * The deadline covers response-body consumption as well as receipt of headers. A provider that
+ * answers headers and then stalls its body retains the request exactly as effectively as one that
+ * never answers at all, so a bound that stops at the headers is not a bound.
+ */
+export const SMS_PROVIDER_TRANSPORT_TIMEOUT_MS = 15_000;
+//# sourceMappingURL=sms-transport.backend.definitions.js.map

package/dist/esm/notifications/sms/models/sms-transport.backend.definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sms-transport.backend.definitions.js","sourceRoot":"","sources":["../../../../../src/notifications/sms/models/sms-transport.backend.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC","sourcesContent":["/**\n * Hard deadline for one external SMS-provider request, including response body consumption.\n *\n * ## Why this is NOT `EMAIL_PROVIDER_TRANSPORT_TIMEOUT_MS` (60s)\n *\n * The bound is a statement about how long the work legitimately takes and about who is waiting,\n * not a house style — which is why this package already carries a measured spread rather than one\n * number: 5s for a CIMD document fetched on behalf of an unauthenticated stranger, 10s for OIDC\n * discovery, 15s for an STS credential, 60s for an email submission or a virus scan, 120s for\n * document extraction, and a per-binding value for ETL and MCP.\n *\n * Two things separate SMS from email, and they push in the same direction:\n *\n * 1. **The payload.** An email submission can carry attachments up to\n *    `OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT`, so 60s is time spent moving bytes the provider has to\n *    accept. An SMS submission is one short form- or JSON-encoded POST whose body is bounded by the\n *    message itself. There is no payload for the extra 45s to serve.\n * 2. **Who is blocked.** Email send is a recoverable job behind a durable lease — nobody is sitting\n *    in front of it, which is what makes a generous bound affordable there. The SMS path is reached\n *    SYNCHRONOUSLY from phone verification and the SMS second factor, so this deadline is the upper\n *    bound on how long a human stares at a sign-in form while an unresponsive vendor holds a socket\n *    open. That is the failure this constant exists to cap.\n *\n * 15s is therefore sized by the person waiting rather than by the bytes, and is still several times\n * the observed round trip of an SMS submission API.\n *\n * The deadline covers response-body consumption as well as receipt of headers. A provider that\n * answers headers and then stalls its body retains the request exactly as effectively as one that\n * never answers at all, so a bound that stops at the headers is not a bound.\n */\nexport const SMS_PROVIDER_TRANSPORT_TIMEOUT_MS = 15_000;\n"]}

package/dist/esm/notifications/sms/services/sms.backend.service.d.ts

@@ -1,13 +1,37 @@
 /**
  * SMS Backend Service
  *
- * Main service for sending SMS messages. Orchestrates:
- * - Provider resolution via ExternalProvidersRegistryBackendService
- * - The provider's own `SMS_PROVIDER` runtime contract, read from the registry, which supplies the
- *   endpoint and the request/response projection
- * - Raw HTTP execution (Basic Auth for Twilio)
+ * Sends one transactional SMS. Orchestrates:
+ * - provider resolution via `ExternalProvidersRegistryBackendService`
+ * - the provider's own `SMS_PROVIDER` runtime contract, read from the registry
+ * - HTTP transport
  *
- * Mirrors the pattern of EmailBackendService for consistency.
+ * ## The line between engine and provider
+ *
+ * Until 2026-09-09 this service narrowed the runtime contract to
+ * `kind: ProviderProtocolRuntimeKind.SMS` — a PROTOCOL many providers can speak — and then built
+ * TWILIO's request unconditionally: `/Accounts/{AccountSid}/Messages.json`, Basic auth, a
+ * form-encoded `To`/`Body`/`From` body, a response read for `sid` and `error_code`. A second
+ * provider declaring `SMS_PROVIDER` would have been sent through Twilio's API carrying its own
+ * credentials, and nothing would have refused it or logged it.
+ *
+ * It now mirrors `EmailBackendService`, which is the arm this problem already has a solved shape
+ * for: the provider declares PURE FUNCTIONS on its contract and the engine owns transport.
+ *
+ *   ENGINE (here)    — resolve the secret, parse it per the declared `auth.credentialShape`,
+ *                      compose the `Authorization` header, substitute `{accountId}` into the
+ *                      contract's `sendEndpointPath`, issue the request, and validate the
+ *                      provider's parsed response against `StandardSMS_SendResponseSchema`.
+ *   PROVIDER         — the endpoint path shape, the request body and its `content-type`, and the
+ *                      projection of the vendor response onto `StandardSMS_SendResponse`.
+ *
+ * There is deliberately no consumer-side adapter registry of the kind billing uses. That shape
+ * exists only because a billing adapter is a CLASS in this package, which the provider package
+ * cannot reach without a reverse dependency edge; an SMS provider owes functions over
+ * `@wildo-ai/external-connectors-models` types, which it can supply directly.
+ *
+ * Every refusal below names the provider, so a misconfigured or unsupported second provider is a
+ * legible failure rather than a silent send through somebody else's API.
  */
 import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
 import type { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service';
@@ -35,14 +59,44 @@ export declare class SMSBackendService {
      */
     send(to: string, body: string, from?: string): Promise<SMSSendResult>;
     /**
-     * Resolve the SMS provider for the SMS capability.
-     * Mirrors EmailBackendService.resolveEmailProvider() pattern.
+     * Resolve the SMS provider for the SMS capability, reading every vendor-specific decision off
+     * the provider's own runtime contract.
+     *
+     * Mirrors `EmailBackendService.resolveEmailProvider()`.
      */
     private resolveSMSProvider;
     /**
-     * Execute the SMS send request via provider.
-     * Uses raw fetch() with Basic Auth for Twilio's REST API (form-encoded).
+     * Compose the send URL from the contract's `baseUrl` and `sendEndpointPath`, substituting the
+     * tokens the resolved credential supplies.
+     *
+     * Refuses a path still holding a `{token}` afterwards. There is no declared token LIST to check
+     * against — this check IS the validation, and it is stronger than a list because it cannot drift
+     * from what substitution actually produced. A misspelled token would otherwise travel to the
+     * vendor as a literal path segment and come back as an opaque 404.
+     */
+    private composeSendEndpoint;
+    /**
+     * Issue the provider's own request and project its response.
+     *
+     * Every vendor-specific decision here comes off the contract. The engine contributes the
+     * `Authorization` header and nothing else.
+     *
+     * That last promise is delivered by `withEngineOwnedHeaders`, and NOT by the ordering this JSDoc
+     * used to cite. Until 2026-09-09 it read "it is applied AFTER the provider's transport headers,
+     * so a provider cannot take authentication over by naming that header" — true only of an
+     * identical spelling. Header names are case-insensitive on the wire and case-SENSITIVE as object
+     * keys, so a provider naming `Authorization` against the engine's `authorization` produced two
+     * keys that `fetch` combines into one comma-joined value, authenticating with neither. The shared
+     * helper drops every spelling of an engine-owned name before the engine's own value is applied.
      */
     private executeProviderRequest;
+    /** Lower-cased header projection, so a provider's parser can index headers by a stable name. */
+    private responseHeadersToRecord;
+    /**
+     * Decode a response body without assuming it is JSON. A vendor error page is frequently HTML or
+     * plain text, and handing the raw string to the provider's parser is more useful than throwing
+     * before it gets a chance to classify.
+     */
+    private bestEffortParseResponseBody;
 }
 //# sourceMappingURL=sms.backend.service.d.ts.map

package/dist/esm/notifications/sms/services/sms.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sms.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/notifications/sms/services/sms.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAEnH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAa1J,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD,qBACa,iBAAiB;IAIS,OAAO,CAAC,QAAQ,CAAC,MAAM;IACV,OAAO,CAAC,QAAQ,CAAC,YAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IACd,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IANzG,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAG3B,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EAC3C,aAAa,EAAE,uBAAuB,EACtB,yBAAyB,EAAE,uCAAuC;IAKlJ;;;;;;OAMG;IACU,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6ClF;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA0F1B;;;OAGG;YACW,sBAAsB;CAqDrC"}
+{"version":3,"file":"sms.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/notifications/sms/services/sms.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAEnH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAsB1J,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+HD,qBACa,iBAAiB;IAIS,OAAO,CAAC,QAAQ,CAAC,MAAM;IACV,OAAO,CAAC,QAAQ,CAAC,YAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IACd,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IANzG,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAG3B,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EAC3C,aAAa,EAAE,uBAAuB,EACtB,yBAAyB,EAAE,uCAAuC;IAKlJ;;;;;;OAMG;IACU,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6ClF;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAyH1B;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;;;;;;;;;;;;OAaG;YACW,sBAAsB;IA8FpC,gGAAgG;IAChG,OAAO,CAAC,uBAAuB;IAQ/B;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;CAUpC"}

package/dist/esm/notifications/sms/services/sms.backend.service.js

@@ -1,13 +1,37 @@
 /**
  * SMS Backend Service
  *
- * Main service for sending SMS messages. Orchestrates:
- * - Provider resolution via ExternalProvidersRegistryBackendService
- * - The provider's own `SMS_PROVIDER` runtime contract, read from the registry, which supplies the
- *   endpoint and the request/response projection
- * - Raw HTTP execution (Basic Auth for Twilio)
+ * Sends one transactional SMS. Orchestrates:
+ * - provider resolution via `ExternalProvidersRegistryBackendService`
+ * - the provider's own `SMS_PROVIDER` runtime contract, read from the registry
+ * - HTTP transport
  *
- * Mirrors the pattern of EmailBackendService for consistency.
+ * ## The line between engine and provider
+ *
+ * Until 2026-09-09 this service narrowed the runtime contract to
+ * `kind: ProviderProtocolRuntimeKind.SMS` — a PROTOCOL many providers can speak — and then built
+ * TWILIO's request unconditionally: `/Accounts/{AccountSid}/Messages.json`, Basic auth, a
+ * form-encoded `To`/`Body`/`From` body, a response read for `sid` and `error_code`. A second
+ * provider declaring `SMS_PROVIDER` would have been sent through Twilio's API carrying its own
+ * credentials, and nothing would have refused it or logged it.
+ *
+ * It now mirrors `EmailBackendService`, which is the arm this problem already has a solved shape
+ * for: the provider declares PURE FUNCTIONS on its contract and the engine owns transport.
+ *
+ *   ENGINE (here)    — resolve the secret, parse it per the declared `auth.credentialShape`,
+ *                      compose the `Authorization` header, substitute `{accountId}` into the
+ *                      contract's `sendEndpointPath`, issue the request, and validate the
+ *                      provider's parsed response against `StandardSMS_SendResponseSchema`.
+ *   PROVIDER         — the endpoint path shape, the request body and its `content-type`, and the
+ *                      projection of the vendor response onto `StandardSMS_SendResponse`.
+ *
+ * There is deliberately no consumer-side adapter registry of the kind billing uses. That shape
+ * exists only because a billing adapter is a CLASS in this package, which the provider package
+ * cannot reach without a reverse dependency edge; an SMS provider owes functions over
+ * `@wildo-ai/external-connectors-models` types, which it can supply directly.
+ *
+ * Every refusal below names the provider, so a misconfigured or unsupported second provider is a
+ * legible failure rather than a silent send through somebody else's API.
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -25,30 +49,88 @@ import { injectable, inject } from 'inversify';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 import { describeCaughtError, projectCaughtErrorLogFields } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
 import { EngineCapability, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';
-import { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind, } from '@wildo-ai/external-connectors-models';
-function parseSMSCredentials(secretValue) {
+import { ExternalProvider_ExchangeProtocol_Kind, SmsProviderCredentialShape, StandardSMS_SendResponseSchema, ProviderProtocolRuntimeKind, } from '@wildo-ai/external-connectors-models';
+import { SMS_PROVIDER_TRANSPORT_TIMEOUT_MS } from '../../../notifications/sms/models/sms-transport.backend.definitions.js';
+import { readResponseTextWithinDeadline } from '../../../security/outbound/outbound-request-deadline.backend.utils.js';
+import { withEngineOwnedHeaders } from '../../../security/outbound/outbound-request-headers.backend.utils.js';
+/** Any `{token}` the contract's `sendEndpointPath` may carry. */
+const ENDPOINT_PATH_TOKEN_PATTERN = /\{([a-zA-Z0-9_]+)\}/g;
+/**
+ * Split a two-part credential bundle on the FIRST occurrence of `separator`, keeping the whole
+ * remainder as the second part.
+ *
+ * `String.prototype.split(sep, 2)` truncates rather than keeping the remainder — `'a:b:c'` yields
+ * `['a', 'b']` and silently drops `':c'` — so the previous implementation would have mangled any
+ * secret containing the separator. Twilio's auth tokens are hex, which is why it never bit.
+ */
+function splitOnFirst(value, separator) {
+    const index = value.indexOf(separator);
+    if (index <= 0 || index === value.length - 1) {
+        return null;
+    }
+    return [value.slice(0, index), value.slice(index + separator.length)];
+}
+/**
+ * Parse an `ACCOUNT_ID_AND_SECRET` bundle out of the resolved secret value.
+ *
+ * Three operator-facing encodings are accepted, in order: a JSON object, `<accountId>|<secret>`,
+ * and `<accountId>:<secret>`. They are the ENV VAR's format, not a per-provider branch — every
+ * provider declaring this credential shape reads the same three.
+ *
+ * The JSON object accepts the SHAPE's own field names (`accountId` / `secret`) and, as an alias,
+ * Twilio's (`accountSid` / `authToken`). The alias is there because deployments already hold
+ * `TWILIO_CREDENTIALS` in that form and breaking every environment buys nothing; the generic names
+ * are preferred because a shape called `ACCOUNT_ID_AND_SECRET` whose only object encoding spoke one
+ * vendor's vocabulary would be the same defect this whole change removes, one level down — a second
+ * provider declaring this shape would have had to tell its operator to write Twilio's key names.
+ */
+function parseAccountIdAndSecret(secretValue) {
     try {
         const parsed = JSON.parse(secretValue);
-        if (typeof parsed.accountSid === 'string'
-            && parsed.accountSid.length > 0
-            && typeof parsed.authToken === 'string'
-            && parsed.authToken.length > 0) {
-            return {
-                accountSid: parsed.accountSid,
-                authToken: parsed.authToken,
-            };
+        const accountId = typeof parsed.accountId === 'string' && parsed.accountId.length > 0
+            ? parsed.accountId
+            : (typeof parsed.accountSid === 'string' && parsed.accountSid.length > 0 ? parsed.accountSid : undefined);
+        const secret = typeof parsed.secret === 'string' && parsed.secret.length > 0
+            ? parsed.secret
+            : (typeof parsed.authToken === 'string' && parsed.authToken.length > 0 ? parsed.authToken : undefined);
+        if (accountId !== undefined && secret !== undefined) {
+            return { accountId, secret };
         }
     }
     catch {
-        // Fallback below handles non-JSON encodings.
+        // Not JSON; the delimited encodings below are the fallback.
     }
-    const [accountSid, authToken] = secretValue.includes('|')
-        ? secretValue.split('|', 2)
-        : secretValue.split(':', 2);
-    if (accountSid && authToken) {
-        return { accountSid, authToken };
+    const parts = splitOnFirst(secretValue, '|') ?? splitOnFirst(secretValue, ':');
+    return parts ? { accountId: parts[0], secret: parts[1] } : null;
+}
+/**
+ * Derive the authorization header and the substitutable path tokens for a declared credential
+ * shape, or `null` when the resolved secret does not parse to that shape.
+ *
+ * The `never` check is what makes this the enforcement point for the whole arm: a member added to
+ * `SmsProviderCredentialShape` without a branch here fails COMPILATION, so the vocabulary cannot
+ * grow a member the engine is unable to authenticate.
+ */
+function resolveSMSCredential(credentialShape, secretValue) {
+    switch (credentialShape) {
+        case SmsProviderCredentialShape.ACCOUNT_ID_AND_SECRET: {
+            const parsed = parseAccountIdAndSecret(secretValue);
+            if (!parsed) {
+                return null;
+            }
+            return {
+                // spec-cite: RFC 7617 §2 — Basic credentials are the base64 of `user-id ":" password`,
+                // carried in the `Authorization` header.
+                authorizationHeaderValue: `Basic ${Buffer.from(`${parsed.accountId}:${parsed.secret}`).toString('base64')}`,
+                // The identifier only. The secret half never reaches a URL.
+                pathTokens: { accountId: parsed.accountId },
+            };
+        }
+        default: {
+            const exhaustiveCheck = credentialShape;
+            return exhaustiveCheck;
+        }
     }
-    return null;
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // SERVICE
@@ -113,8 +195,10 @@ let SMSBackendService = class SMSBackendService {
         }
     }
     /**
-     * Resolve the SMS provider for the SMS capability.
-     * Mirrors EmailBackendService.resolveEmailProvider() pattern.
+     * Resolve the SMS provider for the SMS capability, reading every vendor-specific decision off
+     * the provider's own runtime contract.
+     *
+     * Mirrors `EmailBackendService.resolveEmailProvider()`.
      */
     resolveSMSProvider() {
         const providerId = this.externalProvidersRegistry.getPrimaryProviderForEngineCapability(EngineCapability.SMS);
@@ -124,96 +208,207 @@ let SMSBackendService = class SMSBackendService {
         if (!this.externalProvidersRegistry.isProviderEnabled(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER)) {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, { context: { message: `SMS provider is disabled by external provider configuration: ${providerId}`, providerId } });
         }
-        const secretRef = this.externalProvidersRegistry.getConfiguredProviderSecretRef(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER);
-        const encodedCredentials = secretRef
-            ? this.externalProvidersRegistry.getProviderSecret(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER, secretRef)
-            : undefined;
-        const parsedCredentials = encodedCredentials
-            ? parseSMSCredentials(encodedCredentials)
-            : null;
-        if (!parsedCredentials) {
+        const smsContract = this.externalProvidersRegistry.getProviderRuntimeContract(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER);
+        if (smsContract?.kind !== ProviderProtocolRuntimeKind.SMS) {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
                 context: {
-                    message: `No env-provided credentials configured for SMS provider: ${providerId}`,
+                    message: `No SMS_PROVIDER runtime contract found for provider: ${providerId}`,
                     providerId,
                     capability: EngineCapability.SMS,
-                    secretRef,
                 },
             });
         }
-        const smsContract = this.externalProvidersRegistry.getProviderRuntimeContract(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER);
-        if (smsContract?.kind !== ProviderProtocolRuntimeKind.SMS) {
+        /*
+         * A contract that reached the registry without an executable request shape.
+         *
+         * This is NOT belt-and-braces on top of the type system, and it must not be deleted as such.
+         * A provider reaches a running application through a COMPANION CONTRIBUTION, and that wire
+         * record is deliberately permissive at both ends:
+         * `ProviderCompanionContributionSchema` (`@wildo-ai/saas-models`,
+         * `src/companion/provider-discovery.shared.schemas.ts:120`) is a `z.looseObject` so a record
+         * from a package version this repository never compiled rides through instead of failing the
+         * parse, it announces its `protocols` as bare strings rather than the typed enum, and its
+         * `runtimeImportPath` is resolved and imported at runtime. So the module supplying an SMS
+         * contract can be one no compilation here ever checked.
+         *
+         * Without this guard that case is a `TypeError` from inside transport naming no provider.
+         * With it, the compile-time requirement on the arm and this refusal together are what make
+         * "never silently handed another vendor's shape" true for every declarer, not only the ones
+         * built in this repository.
+         */
+        if (typeof smsContract.buildSendRequest !== 'function' || typeof smsContract.parseSendResponse !== 'function') {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
                 context: {
-                    message: `No SMS_PROVIDER runtime contract found for provider: ${providerId}`,
+                    message: `SMS provider declares no send-request shape and cannot be used: ${providerId}. `
+                        + 'Its SMS_PROVIDER runtime contract must declare buildSendRequest and parseSendResponse.',
+                    providerId,
+                    capability: EngineCapability.SMS,
+                },
+            });
+        }
+        const secretRef = this.externalProvidersRegistry.getConfiguredProviderSecretRef(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER);
+        const encodedCredentials = secretRef
+            ? this.externalProvidersRegistry.getProviderSecret(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER, secretRef)
+            : undefined;
+        const credential = encodedCredentials
+            ? resolveSMSCredential(smsContract.auth.credentialShape, encodedCredentials)
+            : null;
+        if (!credential) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                context: {
+                    message: `No usable credentials configured for SMS provider: ${providerId}`,
                     providerId,
                     capability: EngineCapability.SMS,
+                    secretRef,
+                    // The SHAPE, never the value: it is what an operator needs to fix the env var.
+                    credentialShape: smsContract.auth.credentialShape,
                 },
             });
         }
-        // The framework currently ships a single `kind: ProviderProtocolRuntimeKind.SMS` runtime
-        // contract (Twilio). The execute-request path below assumes the
-        // Twilio REST API shape (`/Accounts/{AccountSid}/Messages.json`,
-        // Basic Auth, form-encoded body). When a second SMS adapter
-        // arrives, factor the provider-specific request shape into the
-        // contract via `sdkFactory` / `buildSendPayload` (mirror of the
-        // email surface) — do NOT reintroduce a `provider === '<ref>'`
-        // literal at this consumer site.
+        const endpoint = this.composeSendEndpoint(providerId, smsContract.baseUrl, smsContract.sendEndpointPath, credential.pathTokens);
         const appConfig = this.configService.config;
         // Get optional from number from provider config
         const providersConfig = appConfig?.providerConfigurations;
         const providerConf = providersConfig?.[providerId]?.[ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER];
         return {
             providerId,
-            accountSid: parsedCredentials.accountSid,
-            authToken: parsedCredentials.authToken,
-            endpoint: smsContract.baseUrl,
+            endpoint,
+            authorizationHeaderValue: credential.authorizationHeaderValue,
+            buildSendRequest: smsContract.buildSendRequest,
+            parseSendResponse: smsContract.parseSendResponse,
             fromNumber: providerConf?.fromNumber,
         };
     }
     /**
-     * Execute the SMS send request via provider.
-     * Uses raw fetch() with Basic Auth for Twilio's REST API (form-encoded).
+     * Compose the send URL from the contract's `baseUrl` and `sendEndpointPath`, substituting the
+     * tokens the resolved credential supplies.
+     *
+     * Refuses a path still holding a `{token}` afterwards. There is no declared token LIST to check
+     * against — this check IS the validation, and it is stronger than a list because it cannot drift
+     * from what substitution actually produced. A misspelled token would otherwise travel to the
+     * vendor as a literal path segment and come back as an opaque 404.
+     */
+    composeSendEndpoint(providerId, baseUrl, sendEndpointPath, pathTokens) {
+        const substituted = sendEndpointPath.replace(ENDPOINT_PATH_TOKEN_PATTERN, (literal, token) => pathTokens[token] ?? literal);
+        const unsubstituted = substituted.match(ENDPOINT_PATH_TOKEN_PATTERN);
+        if (unsubstituted) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                context: {
+                    message: `SMS provider declares an endpoint path with unsubstitutable tokens: ${providerId}`,
+                    providerId,
+                    sendEndpointPath,
+                    unsubstitutedTokens: unsubstituted,
+                },
+            });
+        }
+        return `${baseUrl}${substituted}`;
+    }
+    /**
+     * Issue the provider's own request and project its response.
+     *
+     * Every vendor-specific decision here comes off the contract. The engine contributes the
+     * `Authorization` header and nothing else.
+     *
+     * That last promise is delivered by `withEngineOwnedHeaders`, and NOT by the ordering this JSDoc
+     * used to cite. Until 2026-09-09 it read "it is applied AFTER the provider's transport headers,
+     * so a provider cannot take authentication over by naming that header" — true only of an
+     * identical spelling. Header names are case-insensitive on the wire and case-SENSITIVE as object
+     * keys, so a provider naming `Authorization` against the engine's `authorization` produced two
+     * keys that `fetch` combines into one comma-joined value, authenticating with neither. The shared
+     * helper drops every spelling of an engine-owned name before the engine's own value is applied.
      */
     async executeProviderRequest(providerConfig, request) {
-        // Build the URL (Twilio uses /Accounts/{AccountSid}/Messages.json)
-        const url = `${providerConfig.endpoint}/Accounts/${providerConfig.accountSid}/Messages.json`;
-        // Build Basic Auth header
-        const basicAuth = Buffer.from(`${providerConfig.accountSid}:${providerConfig.authToken}`).toString('base64');
-        // Build form-encoded body from transformer output
-        const formBody = new URLSearchParams({
-            To: request.to,
-            Body: request.body,
-            ...(request.from ? { From: request.from } : {}),
-        }).toString();
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: {
-                [WildoHeaderKeys.CONTENT_TYPE]: 'application/x-www-form-urlencoded',
-                [WildoHeaderKeys.AUTHORIZATION]: `Basic ${basicAuth}`,
-            },
-            body: formBody,
-        });
-        if (!response.ok) {
-            const errorBody = await response.text();
+        const providerRequest = providerConfig.buildSendRequest(request);
+        /*
+         * THE DEADLINE, and it stays armed through response-body consumption.
+         *
+         * This request had no bound at all until 2026-09-09. It is reached synchronously from phone
+         * verification and the SMS second factor, so a vendor that accepts a connection and then never
+         * answers held a sign-in open for as long as the socket lived — Node's `fetch` imposes no
+         * timeout of its own, and nothing above this frame imposed one either.
+         *
+         * `clearTimeout` sits in a `finally` that wraps BOTH the request and the body read, which is
+         * the half that is easy to lose: a provider that returns headers and then stalls its body
+         * retains the request exactly as effectively as one that never returns at all.
+         */
+        const abortController = new AbortController();
+        const timeoutHandle = setTimeout(() => abortController.abort(new Error(`SMS provider request exceeded ${SMS_PROVIDER_TRANSPORT_TIMEOUT_MS}ms`)), SMS_PROVIDER_TRANSPORT_TIMEOUT_MS);
+        let response;
+        let responseText;
+        try {
+            response = await fetch(providerConfig.endpoint, {
+                method: 'POST',
+                headers: withEngineOwnedHeaders(providerRequest.transportHeaders, {
+                    [WildoHeaderKeys.AUTHORIZATION]: providerConfig.authorizationHeaderValue,
+                }),
+                body: providerRequest.body,
+                signal: abortController.signal,
+            });
+            responseText = await readResponseTextWithinDeadline(response, abortController.signal);
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+        const parserInput = {
+            status: response.status,
+            headers: this.responseHeadersToRecord(response.headers),
+            body: this.bestEffortParseResponseBody(responseText),
+        };
+        /*
+         * The provider decides acceptance, and the engine holds it to the standard shape.
+         *
+         * Both halves matter. Twilio reports a per-message failure inside a 2xx body, so an HTTP-status
+         * check alone is not an answer — that is why the decision is the provider's. And the validation
+         * replaces an unchecked `responseData.status as StandardSMS_SendResponse['status']` that let any
+         * string through: Twilio's own `accepted` would have landed in a field whose vocabulary does not
+         * contain it.
+         */
+        const parsed = StandardSMS_SendResponseSchema.safeParse(providerConfig.parseSendResponse(parserInput));
+        if (!parsed.success) {
             throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {
                 context: {
-                    message: `SMS provider returned error: ${response.status}`,
+                    message: `SMS provider response parser violated StandardSMS_SendResponse: ${providerConfig.providerId}`,
                     providerId: providerConfig.providerId,
                     statusCode: response.status,
-                    errorBody,
+                    validationError: parsed.error.message,
+                },
+            });
+        }
+        if (!parsed.data.success) {
+            throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {
+                context: {
+                    message: `SMS provider rejected the message: ${providerConfig.providerId}`,
+                    providerId: providerConfig.providerId,
+                    statusCode: response.status,
+                    errorBody: responseText,
                 }
             });
         }
-        const responseData = await response.json();
-        const hasProviderError = responseData.error_code !== undefined && responseData.error_code !== null;
-        return {
-            success: !hasProviderError,
-            messageId: String(responseData.sid ?? responseData.messageId ?? `${providerConfig.providerId}-${Date.now()}`),
-            status: hasProviderError
-                ? 'failed'
-                : typeof responseData.status === 'string' ? responseData.status : undefined,
-        };
+        return parsed.data;
+    }
+    /** Lower-cased header projection, so a provider's parser can index headers by a stable name. */
+    responseHeadersToRecord(headers) {
+        const result = {};
+        headers.forEach((value, key) => {
+            result[key.toLowerCase()] = value;
+        });
+        return result;
+    }
+    /**
+     * Decode a response body without assuming it is JSON. A vendor error page is frequently HTML or
+     * plain text, and handing the raw string to the provider's parser is more useful than throwing
+     * before it gets a chance to classify.
+     */
+    bestEffortParseResponseBody(responseText) {
+        if (responseText.length === 0) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(responseText);
+        }
+        catch {
+            return responseText;
+        }
     }
 };
 SMSBackendService = __decorate([