@carrierllc/mcp 0.13.51 → 0.13.57

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.
@@ -1913,7 +1913,7 @@ function storefrontScreen(input) {
1913
1913
  // package.json
1914
1914
  var package_default = {
1915
1915
  name: "@carrierllc/mcp",
1916
- version: "0.13.51",
1916
+ version: "0.13.57",
1917
1917
  description: "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
1918
1918
  license: "MIT",
1919
1919
  author: "Carrier (Lifecycle Innovations Limited)",
@@ -1959,7 +1959,7 @@ var package_default = {
1959
1959
  "@clack/prompts": "^0.7.0",
1960
1960
  "@clerk/backend": "^3.18.1",
1961
1961
  "@modelcontextprotocol/ext-apps": "^1.7.5",
1962
- "@modelcontextprotocol/sdk": "^1.31.0",
1962
+ "@modelcontextprotocol/sdk": "^1.32.0",
1963
1963
  "@noble/hashes": "^2.3.0",
1964
1964
  "@sentry/cloudflare": "^10.65.0",
1965
1965
  aws4fetch: "^1.0.20",
@@ -3184,7 +3184,7 @@ async function runWithBudget(method, attempt, budget = ocsBudgetFor(method)) {
3184
3184
  throw lastTimeout ?? new OcsTimeoutError(method, budget.attemptMs, budget.totalMs, Math.max(attempts, 1));
3185
3185
  }
3186
3186
 
3187
- // ../../packages/ocs-client/dist/chunk-VDRJZSQW.js
3187
+ // ../../packages/ocs-client/dist/chunk-ABY2BUXP.js
3188
3188
  var RATE_LIMIT = 10;
3189
3189
  var WINDOW_MS = 1e3;
3190
3190
  var windows = /* @__PURE__ */ new Map();
@@ -3451,6 +3451,16 @@ function assertBareIntParam(method, params) {
3451
3451
  );
3452
3452
  }
3453
3453
  var SINGLE_ATTEMPT_METHODS = /* @__PURE__ */ new Set(["affectPackageToSubscriber", "addSubscriberPackage", "deleteSubscriberPackage"]);
3454
+ var OcsHttpError = class extends Error {
3455
+ constructor(status, method) {
3456
+ super("[" + method + "] HTTP " + status);
3457
+ this.status = status;
3458
+ this.method = method;
3459
+ this.name = "OcsHttpError";
3460
+ }
3461
+ status;
3462
+ method;
3463
+ };
3454
3464
  var OcsApiError = class extends Error {
3455
3465
  constructor(code, message, method, details = {}) {
3456
3466
  super(`[${method}] OCS error ${code}: ${message}`);
@@ -3496,6 +3506,11 @@ var OcsContractError = class _OcsContractError extends Error {
3496
3506
  };
3497
3507
  function ocsErrorMessage(code, rawMsg, rawBody) {
3498
3508
  switch (code) {
3509
+ case 9:
3510
+ return {
3511
+ message: "OCS source IP not authorised (code 9 SRC_IP_NOT_AUTHORISED). This reseller token has an IP allowlist configured on eSIMVault. Route traffic through the fixed-egress proxy (CARRIER_OCS_PROXY_URL / fixedEgress) and ensure its static IP is whitelisted.",
3512
+ details: {}
3513
+ };
3499
3514
  case 12:
3500
3515
  return {
3501
3516
  message: "OCS resource is read-only (code 12). The package/subscriber/account state does not allow this mutation. Often returned for end-of-life subscribers or finalized invoices.",
@@ -3543,12 +3558,16 @@ async function retryWithBackoff(fn) {
3543
3558
  return await fn();
3544
3559
  } catch (err) {
3545
3560
  lastError = err;
3561
+ if (err instanceof OcsHttpError) throw err;
3546
3562
  if (err instanceof OcsApiError) {
3547
3563
  if (err.code !== 100) throw err;
3548
3564
  maxRetries = TRAFFIC_CONTROL_MAX_RETRIES;
3549
3565
  backoffBaseMs = TRAFFIC_CONTROL_BACKOFF_BASE_MS;
3550
3566
  backoffMaxMs = TRAFFIC_CONTROL_BACKOFF_MAX_MS;
3551
3567
  }
3568
+ if (err instanceof OcsProxyError) {
3569
+ if (err.status === 401 || err.status === 403) throw err;
3570
+ }
3552
3571
  if (err instanceof OcsContractError) {
3553
3572
  throw err;
3554
3573
  }
@@ -3562,13 +3581,44 @@ async function retryWithBackoff(fn) {
3562
3581
  function isAbortError(err) {
3563
3582
  return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError" || /aborted|timed? ?out/i.test(err.message));
3564
3583
  }
3584
+ var OcsProxyError = class extends Error {
3585
+ constructor(message, status, cause) {
3586
+ super(`[ocs-client] Fixed egress proxy error: ${message}`);
3587
+ this.status = status;
3588
+ this.cause = cause;
3589
+ this.name = "OcsProxyError";
3590
+ }
3591
+ status;
3592
+ cause;
3593
+ };
3594
+ var configuredFixedEgress;
3595
+ function fixedEgressFromEnv(env) {
3596
+ if (!env) return void 0;
3597
+ const proxyUrl = (env["CARRIER_OCS_PROXY_URL"] ?? env["OCS_FIXED_EGRESS_PROXY_URL"] ?? env["OCS_PROXY_URL"])?.trim();
3598
+ const required = env["CARRIER_OCS_REQUIRE_FIXED_EGRESS"] === "true" || env["CARRIER_OCS_REQUIRE_FIXED_EGRESS"] === true;
3599
+ if (!proxyUrl && !required) return void 0;
3600
+ const proxySecret = env["CARRIER_OCS_PROXY_SECRET"] ?? env["OCS_FIXED_EGRESS_PROXY_SECRET"] ?? env["OCS_PROXY_SECRET"];
3601
+ const targetHost = env["CARRIER_OCS_PROXY_TARGET_HOST"] ?? env["OCS_FIXED_EGRESS_TARGET_HOST"];
3602
+ const fallbackMode = env["CARRIER_OCS_PROXY_FALLBACK"] ?? env["OCS_PROXY_FALLBACK"];
3603
+ const requireFixedEgress = env["CARRIER_OCS_REQUIRE_FIXED_EGRESS"] === "true" || env["CARRIER_OCS_REQUIRE_FIXED_EGRESS"] === true;
3604
+ const enabledRaw = env["CARRIER_OCS_PROXY_ENABLED"];
3605
+ const enabled = enabledRaw !== void 0 ? enabledRaw === "true" || enabledRaw === true || enabledRaw === "1" : true;
3606
+ return {
3607
+ proxyUrl,
3608
+ proxySecret,
3609
+ targetHost,
3610
+ fallbackMode: fallbackMode ?? "strict",
3611
+ requireFixedEgress,
3612
+ enabled
3613
+ };
3614
+ }
3565
3615
  var OcsClient = class {
3566
3616
  /**
3567
3617
  * @param baseUrl OCS base URL without trailing slash (e.g. https://ocs.esimvault.cloud).
3568
3618
  * @param _defaultToken Default API token; identifies the reseller for rate-floor keying.
3569
3619
  * @param _priority Call priority: "interactive" (MCP tool calls, 80% capacity) or
3570
3620
  * "batch" (cron/poll callers, 20% capacity). Default: "interactive".
3571
- * @param options Contract-enforcement opt-outs (see `OcsClientOptions`).
3621
+ * @param options Contract-enforcement opt-outs and proxy routing (see `OcsClientOptions`).
3572
3622
  */
3573
3623
  constructor(baseUrl, _defaultToken, _priority = "interactive", options = {}) {
3574
3624
  this._defaultToken = _defaultToken;
@@ -3579,6 +3629,46 @@ var OcsClient = class {
3579
3629
  this._strictMethods = options.strictMethods ?? false;
3580
3630
  this._validateResponses = options.validateResponses ?? true;
3581
3631
  this._strictValidation = options.strictValidation ?? false;
3632
+ const envConfig = options.env ? fixedEgressFromEnv(options.env) : configuredFixedEgress ?? (typeof process !== "undefined" && process?.env ? fixedEgressFromEnv(process.env) : void 0);
3633
+ const optConfig = options.fixedEgress ?? {
3634
+ proxyUrl: options.fixedEgressProxyUrl,
3635
+ proxySecret: options.fixedEgressProxySecret,
3636
+ targetHost: options.fixedEgressTargetHost,
3637
+ requireFixedEgress: options.requireFixedEgress,
3638
+ fallbackMode: options.fallbackMode
3639
+ };
3640
+ const resolvedProxyUrl = optConfig.proxyUrl?.trim() || envConfig?.proxyUrl;
3641
+ const resolvedProxySecret = optConfig.proxySecret ?? envConfig?.proxySecret;
3642
+ const resolvedTargetHost = optConfig.targetHost ?? envConfig?.targetHost ?? (this.baseUrl ? new URL(this.baseUrl).hostname : "ocs.esimvault.cloud");
3643
+ const resolvedRequire = Boolean(optConfig.requireFixedEgress || envConfig?.requireFixedEgress);
3644
+ const resolvedFallback = optConfig.fallbackMode ?? envConfig?.fallbackMode ?? "strict";
3645
+ const resolvedEnabled = optConfig.enabled ?? envConfig?.enabled ?? Boolean(resolvedProxyUrl);
3646
+ if (resolvedProxyUrl && resolvedEnabled) {
3647
+ if (!resolvedProxySecret?.trim()) {
3648
+ throw new OcsProxyError("Fixed OCS egress proxy is configured but proxySecret is missing");
3649
+ }
3650
+ let proxyUrl;
3651
+ try {
3652
+ proxyUrl = new URL(resolvedProxyUrl);
3653
+ } catch {
3654
+ throw new OcsProxyError("Proxy URL must be a valid HTTPS URL");
3655
+ }
3656
+ if (proxyUrl.protocol !== "https:" || proxyUrl.username || proxyUrl.password || proxyUrl.search || proxyUrl.hash) {
3657
+ throw new OcsProxyError("Proxy URL must use HTTPS without credentials, query or fragment");
3658
+ }
3659
+ this._fixedEgress = {
3660
+ proxyUrl: resolvedProxyUrl,
3661
+ proxySecret: resolvedProxySecret,
3662
+ targetHost: resolvedTargetHost,
3663
+ requireFixedEgress: resolvedRequire,
3664
+ fallbackMode: resolvedFallback,
3665
+ enabled: true
3666
+ };
3667
+ } else if (resolvedRequire) {
3668
+ throw new OcsProxyError("Fixed OCS egress is required but no authenticated proxy is configured");
3669
+ } else {
3670
+ this._fixedEgress = void 0;
3671
+ }
3582
3672
  }
3583
3673
  _defaultToken;
3584
3674
  _priority;
@@ -3586,10 +3676,14 @@ var OcsClient = class {
3586
3676
  _strictMethods;
3587
3677
  _validateResponses;
3588
3678
  _strictValidation;
3679
+ _fixedEgress;
3589
3680
  // Per-instance (NOT static): a static set would dedup across requests in a
3590
3681
  // reused Worker isolate and silently swallow recurring contract-drift warnings.
3591
3682
  _warnedMethods = /* @__PURE__ */ new Set();
3592
3683
  _warnedValidation = /* @__PURE__ */ new Set();
3684
+ get fixedEgress() {
3685
+ return this._fixedEgress;
3686
+ }
3593
3687
  async call(method, params = {}, token) {
3594
3688
  if (OCS_FORBIDDEN_METHODS.has(method)) {
3595
3689
  throw new OcsUnknownMethodError(method);
@@ -3607,39 +3701,115 @@ var OcsClient = class {
3607
3701
  if (!tok) {
3608
3702
  throw new OcsApiError(-1, "No OCS API token provided", method);
3609
3703
  }
3610
- const url = `${this.baseUrl}/v1?token=${tok}`;
3704
+ const directUrl = `${this.baseUrl}/v1?token=${encodeURIComponent(tok)}`;
3705
+ const useProxy = Boolean(this._fixedEgress?.enabled && this._fixedEgress?.proxyUrl);
3706
+ if (this._fixedEgress?.requireFixedEgress && !useProxy) {
3707
+ throw new OcsProxyError("Fixed OCS egress is required but no authenticated proxy is configured");
3708
+ }
3709
+ let proxyEndpoint = this._fixedEgress?.proxyUrl ?? "";
3710
+ if (useProxy && !proxyEndpoint.includes("/v1")) {
3711
+ proxyEndpoint = `${proxyEndpoint}/v1`;
3712
+ }
3713
+ const url = useProxy ? proxyEndpoint : directUrl;
3611
3714
  assertBareIntParam(method, params);
3612
3715
  const wireParams = applyParamRenames(method, params);
3613
3716
  const shapedParams = nestsSubscriberId(method) ? nestSubscriberIdParam(wireParams) : wireParams;
3614
3717
  const body = JSON.stringify({ [method]: shapedParams });
3615
3718
  const singleAttempt = SINGLE_ATTEMPT_METHODS.has(method);
3719
+ const directFallback = !this._fixedEgress?.requireFixedEgress && this._fixedEgress?.fallbackMode === "fallback" && !singleAttempt;
3616
3720
  const send = async () => {
3617
3721
  await acquireToken(tok);
3618
3722
  await acquireEndpointSlot(tok, method, this._priority);
3619
3723
  return runWithBudget(method, async (signal, attemptMs) => {
3620
3724
  let res;
3621
- try {
3622
- res = await fetch(url, {
3623
- method: "POST",
3624
- headers: { "Content-Type": "application/json" },
3625
- body,
3626
- signal
3627
- });
3628
- } catch (err) {
3629
- if (isAbortError(err)) {
3630
- throw new OcsTimeoutError(method, attemptMs);
3725
+ if (useProxy) {
3726
+ const proxyHeaders = {
3727
+ "Content-Type": "application/json",
3728
+ "X-OCS-Target-Host": this._fixedEgress.targetHost ?? new URL(this.baseUrl).hostname,
3729
+ "X-OCS-Target-Path": `/v1?token=${encodeURIComponent(tok)}`,
3730
+ "X-Carrier-Target-Base-Url": this.baseUrl
3731
+ };
3732
+ if (this._fixedEgress.proxySecret) {
3733
+ proxyHeaders["Authorization"] = `Bearer ${this._fixedEgress.proxySecret}`;
3734
+ proxyHeaders["X-Carrier-Proxy-Secret"] = this._fixedEgress.proxySecret;
3735
+ }
3736
+ try {
3737
+ res = await fetch(url, {
3738
+ method: "POST",
3739
+ headers: proxyHeaders,
3740
+ body,
3741
+ signal
3742
+ });
3743
+ } catch (err) {
3744
+ if (isAbortError(err)) {
3745
+ throw new OcsTimeoutError(method, attemptMs);
3746
+ }
3747
+ if (directFallback) {
3748
+ console.warn(
3749
+ `[ocs-client] fixed-egress proxy network failure (${err instanceof Error ? err.message : String(err)}), falling back to direct OCS call`
3750
+ );
3751
+ try {
3752
+ res = await fetch(directUrl, {
3753
+ method: "POST",
3754
+ headers: { "Content-Type": "application/json" },
3755
+ body,
3756
+ signal
3757
+ });
3758
+ } catch (fallbackErr) {
3759
+ if (isAbortError(fallbackErr)) {
3760
+ throw new OcsTimeoutError(method, attemptMs);
3761
+ }
3762
+ throw fallbackErr;
3763
+ }
3764
+ } else {
3765
+ throw new OcsProxyError(`Proxy connection failure: ${err instanceof Error ? err.message : String(err)}`, void 0, err);
3766
+ }
3767
+ }
3768
+ if (res.status === 401 || res.status === 403) {
3769
+ throw new OcsProxyError(`Proxy authentication rejected (HTTP ${res.status} ${res.statusText})`, res.status);
3770
+ }
3771
+ if (res.status >= 502 && res.status <= 504) {
3772
+ if (directFallback) {
3773
+ console.warn(
3774
+ `[ocs-client] fixed-egress proxy returned HTTP ${res.status}, falling back to direct OCS call`
3775
+ );
3776
+ try {
3777
+ res = await fetch(directUrl, {
3778
+ method: "POST",
3779
+ headers: { "Content-Type": "application/json" },
3780
+ body,
3781
+ signal
3782
+ });
3783
+ } catch (fallbackErr) {
3784
+ if (isAbortError(fallbackErr)) {
3785
+ throw new OcsTimeoutError(method, attemptMs);
3786
+ }
3787
+ throw fallbackErr;
3788
+ }
3789
+ } else {
3790
+ throw new OcsProxyError(`Proxy upstream gateway failure: HTTP ${res.status} ${res.statusText}`, res.status);
3791
+ }
3792
+ }
3793
+ } else {
3794
+ try {
3795
+ res = await fetch(directUrl, {
3796
+ method: "POST",
3797
+ headers: { "Content-Type": "application/json" },
3798
+ body,
3799
+ signal
3800
+ });
3801
+ } catch (err) {
3802
+ if (isAbortError(err)) {
3803
+ throw new OcsTimeoutError(method, attemptMs);
3804
+ }
3805
+ throw err;
3631
3806
  }
3632
- throw err;
3633
3807
  }
3634
3808
  if (res.status >= 500) {
3635
3809
  throw new Error(`HTTP ${res.status} ${res.statusText}`);
3636
3810
  }
3637
3811
  if (!res.ok) {
3638
- throw new OcsApiError(
3639
- res.status,
3640
- `HTTP ${res.status} ${res.statusText}`,
3641
- method
3642
- );
3812
+ throw new OcsHttpError(res.status, method);
3643
3813
  }
3644
3814
  let json;
3645
3815
  try {
@@ -5630,4 +5800,4 @@ export {
5630
5800
  package_default,
5631
5801
  CARRIER_VERSION
5632
5802
  };
5633
- //# sourceMappingURL=chunk-NPAD6AA7.js.map
5803
+ //# sourceMappingURL=chunk-Y3WMFQAV.js.map