@topolo/sdk 0.10.3 → 0.10.4

package/dist/node/credential-store.cjs

@@ -23,6 +23,8 @@ __export(credential_store_exports, {
   ENVIRONMENT_DEFAULT_SERVICE_URLS: () => ENVIRONMENT_DEFAULT_SERVICE_URLS,
   TOPOLO_ENVIRONMENTS: () => TOPOLO_ENVIRONMENTS,
   activateContext: () => activateContext,
+  assertServiceUrlForEnvironment: () => assertServiceUrlForEnvironment,
+  assertTopoloServiceUrlEnvironment: () => assertTopoloServiceUrlEnvironment,
   clearProfileCredential: () => clearProfileCredential,
   configPath: () => configPath,
   contextKey: () => contextKey,
@@ -38,6 +40,7 @@ __export(credential_store_exports, {
   resolveServiceUrls: () => resolveServiceUrls,
   resolvedProfileConfig: () => resolvedProfileConfig,
   selectedEnvironment: () => selectedEnvironment,
+  topoloServiceOrigins: () => topoloServiceOrigins,
   writeConfig: () => writeConfig,
   writeContextCredential: () => writeContextCredential,
   writeProfileConfig: () => writeProfileConfig
@@ -57,6 +60,90 @@ var TopoloSdkError = class extends Error {
     this.code = code;
   }
 };
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "action_app_identity_unavailable",
+  "action_authentication_required",
+  "action_catalog_summary_unavailable",
+  "action_catalog_unavailable",
+  "action_contract_mismatch",
+  "action_permission_required",
+  "action_runtime_authorization_required",
+  "action_service_not_allowed",
+  "auth_error",
+  "authentication_required",
+  "authorization_pending",
+  "bad_sig",
+  "confirmation_required",
+  "dependency_unavailable",
+  "environment_mismatch",
+  "environment_service_url_required",
+  "expired_token",
+  "forbidden",
+  "http_error",
+  "immutable_drift",
+  "integration_dependency_unavailable",
+  "integration_misconfigured",
+  "invalid_action",
+  "invalid_action_input",
+  "invalid_grant",
+  "invalid_input",
+  "invalid_token",
+  "mcp_error",
+  "membership_required",
+  "network_error",
+  "organization_context_required",
+  "organization_enrollment_required",
+  "permission_denied",
+  "rate_limited",
+  "request_failed",
+  "service_catalog_unavailable",
+  "service_path_origin_mismatch",
+  "service_required",
+  "slow_down",
+  "state_conflict",
+  "unauthorized",
+  "unknown_action",
+  "unknown_service"
+]);
+var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
+var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
+var RETRY_AFTER_DATE_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+var PUBLIC_DETAIL_SOURCES = /* @__PURE__ */ new Set([
+  "api_key_introspection",
+  "api_key_validation",
+  "auth_context",
+  "auth_validate",
+  "catalog",
+  "credential",
+  "runtime",
+  "service_token_provider",
+  "service_verify_key",
+  "token_validation",
+  "upstream"
+]);
+function canonicalTopoloErrorCode(value) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim().toLowerCase();
+  if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
+  return candidate;
+}
+function canonicalTopoloRequestId(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  return TOPOLO_REQUEST_ID_PATTERN.test(candidate) || CLOUDFLARE_RAY_ID_PATTERN.test(candidate) ? candidate : void 0;
+}
+function canonicalTopoloRetryAfter(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  if (/^\d{1,10}$/.test(candidate) || RETRY_AFTER_DATE_PATTERN.test(candidate)) return candidate;
+  return void 0;
+}
+function canonicalTopoloRequired(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item) => typeof item === "string" && PERMISSION_PATTERN.test(item)))].slice(0, 32);
+}
 var TopoloAuthError = class extends TopoloSdkError {
   status;
   body;
@@ -64,27 +151,91 @@ var TopoloAuthError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, code = "auth_error", options = {}) {
-    super(code, message);
+    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
     this.service = options.service;
     this.path = options.path;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
-function extractHttpErrorCode(body) {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+function extractTopoloServiceErrorCode(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record = body;
-  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const topLevel = canonicalTopoloErrorCode(record.code);
+  if (topLevel) return topLevel;
   const nested = record.error;
+  const nestedString = canonicalTopoloErrorCode(nested);
+  if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    if (typeof code === "string" && code.trim()) return code.trim();
+    const nestedCode = canonicalTopoloErrorCode(code);
+    if (nestedCode) return nestedCode;
+  }
+  return null;
+}
+function serviceErrorCode(body, fallback) {
+  return extractTopoloServiceErrorCode(body) ?? fallback;
+}
+function extractTopoloServiceErrorDetails(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record = body;
+  let candidate = record.details;
+  const nested = record.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const nestedRecord = nested;
+    if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
+  }
+  if (candidate === void 0) candidate = record;
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return void 0;
+  const source = candidate;
+  const safe = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (/present$/i.test(key) && typeof value === "boolean") {
+      safe[key] = value;
+      continue;
+    }
+    if (key === "retryable" && typeof value === "boolean") {
+      safe.retryable = value;
+      continue;
+    }
+    if (key === "code") {
+      const sanitized = canonicalTopoloErrorCode(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "source") {
+      const sanitized = typeof value === "string" ? value.trim().toLowerCase() : "";
+      if (PUBLIC_DETAIL_SOURCES.has(sanitized)) safe.source = sanitized;
+      continue;
+    }
+    if (key === "dependency" || key === "platform") {
+      safe[`${key}Present`] = value !== null && value !== void 0;
+      continue;
+    }
+    if (key === "error" && !safe.code) {
+      const sanitized = canonicalTopoloErrorCode(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "required" && Array.isArray(value)) {
+      const required = canonicalTopoloRequired(value);
+      if (required.length) safe.required = required;
+      continue;
+    }
+    if (["missingFields", "fields", "paths"].includes(key) && Array.isArray(value)) {
+      const paths = value.filter((item) => typeof item === "string" && /^[$.a-z0-9_[\]-]{1,160}$/i.test(item));
+      if (paths.length) safe[key] = paths;
+    }
   }
-  return "http_error";
+  return Object.keys(safe).length ? safe : void 0;
 }
 var TopoloHttpError = class extends TopoloSdkError {
   status;
@@ -93,15 +244,19 @@ var TopoloHttpError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(service, path, status, body, message, options = {}) {
-    super(extractHttpErrorCode(body), message ?? `HTTP ${status} from ${service}${path}`);
+    super(serviceErrorCode(body, "http_error"), message ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = path;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? body : { details: options.details }
+    );
   }
 };
 
@@ -214,13 +369,11 @@ var TopoloOAuth = class {
   }
 };
 
-// src/node/credential-store.ts
-var TOPOLO_ENVIRONMENTS = ["production", "staging", "development", "local"];
-function contextKey(contextType, organizationId) {
-  return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
-}
-var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
+// src/environment.ts
+var TOPOLO_RUNTIME_ENVIRONMENTS = ["production", "staging", "development", "local"];
+var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
   production: {
+    auth: "https://auth.topolo.app",
     developers: "https://developers.topolo.app"
   },
   staging: {
@@ -234,6 +387,58 @@ var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
   },
   local: {}
 };
+function hostnameHasSuffix(hostname, suffix) {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+function workersDevAccountMatches(hostname, account) {
+  if (!hostname.endsWith(".workers.dev")) return false;
+  const labels = hostname.slice(0, -".workers.dev".length).split(".");
+  return labels.length >= 2 && labels.at(-1) === account;
+}
+function originMatchesEnvironment(url, environment) {
+  const hostname = url.hostname.toLowerCase();
+  if (environment === "local") {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+  }
+  if (url.protocol !== "https:") return false;
+  if (environment === "production") {
+    return hostnameHasSuffix(hostname, "topolo.app") || hostnameHasSuffix(hostname, "topolo.io") || workersDevAccountMatches(hostname, "topolo");
+  }
+  if (environment === "staging") {
+    return hostnameHasSuffix(hostname, "stg.topolo.us") || workersDevAccountMatches(hostname, "topolo-staging");
+  }
+  return hostnameHasSuffix(hostname, "topolo.dev") || workersDevAccountMatches(hostname, "topolo-development");
+}
+function assertTopoloServiceUrlEnvironment(service, value, environment) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment(url, environment)) {
+    throw new TopoloSdkError(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment(service, value, environment)
+    ])
+  );
+}
+
+// src/node/credential-store.ts
+var TOPOLO_ENVIRONMENTS = TOPOLO_RUNTIME_ENVIRONMENTS;
+function contextKey(contextType, organizationId) {
+  return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
+}
+var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
@@ -351,15 +556,17 @@ function credentialSourceFromConfig(config, environment = selectedEnvironment())
   const prefix = envVarPrefix(environment);
   if (process.env[`${prefix}_API_KEY`]) return `env:${prefix}_API_KEY`;
   if (process.env[`${prefix}_ACCESS_TOKEN`]) return `env:${prefix}_ACCESS_TOKEN`;
-  if (process.env.TOPOLO_API_KEY) return "env:TOPOLO_API_KEY";
-  if (process.env.TOPOLO_ACCESS_TOKEN) return "env:TOPOLO_ACCESS_TOKEN";
+  if (environment === "production" && process.env.TOPOLO_API_KEY) return "env:TOPOLO_API_KEY";
+  if (environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
+    return "env:TOPOLO_ACCESS_TOKEN";
+  }
   return profileForEnvironment(config, environment).credential ? "config-file" : "none";
 }
 async function resolveCredential(environment = selectedEnvironment()) {
   const prefix = envVarPrefix(environment);
-  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? (environment === "production" ? process.env.TOPOLO_API_KEY : void 0);
   if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? (environment === "production" ? process.env.TOPOLO_ACCESS_TOKEN : void 0);
   if (accessToken) return { kind: "access_token", accessToken };
   const config = await readConfig();
   return profileForEnvironment(config, environment).credential ?? null;
@@ -367,7 +574,7 @@ async function resolveCredential(environment = selectedEnvironment()) {
 var REFRESH_SKEW_SECONDS = 60;
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
   const prefix = envVarPrefix(environment);
-  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || environment === "production" && process.env.TOPOLO_API_KEY || environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
     return resolveCredential(environment);
   }
   const config = await readConfig();
@@ -377,9 +584,16 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
   if (!cred.refreshToken || !profile.oauthClientId) return cred;
   const now = Math.floor(Date.now() / 1e3);
   if (!options.force && cred.expiresAt && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+  if (environment === "local" && !serviceUrls?.auth) {
+    throw new TopoloSdkError(
+      "environment_service_url_required",
+      "Local Topolo credential refresh requires an explicit local Auth service origin."
+    );
+  }
   try {
     const oauth = new TopoloOAuth({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+      serviceUrls
     });
     const tokens = await oauth.refreshToken({
       clientId: profile.oauthClientId,
@@ -420,9 +634,16 @@ async function refreshContextCredentialIfNeeded(environment, key, options = {})
   if (!credential.refreshToken || !oauthClientId) return credential;
   const now = Math.floor(Date.now() / 1e3);
   if (!options.force && credential.expiresAt && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+  if (environment === "local" && !serviceUrls?.auth) {
+    throw new TopoloSdkError(
+      "environment_service_url_required",
+      "Local Topolo context refresh requires an explicit local Auth service origin."
+    );
+  }
   try {
     const oauth = new TopoloOAuth({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+      serviceUrls
     });
     const tokens = await oauth.refreshToken({
       clientId: oauthClientId,
@@ -469,7 +690,12 @@ function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
       merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
     }
   }
-  return Object.keys(merged).length > 0 ? merged : void 0;
+  const origins = topoloServiceOrigins(merged, environment);
+  return Object.keys(origins).length > 0 ? origins : void 0;
+}
+function assertServiceUrlForEnvironment(service, serviceUrl, environment = selectedEnvironment()) {
+  if (!serviceUrl) return;
+  assertTopoloServiceUrlEnvironment(service, serviceUrl, environment);
 }
 function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   const profile = profileForEnvironment(config, environment);
@@ -485,6 +711,8 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   ENVIRONMENT_DEFAULT_SERVICE_URLS,
   TOPOLO_ENVIRONMENTS,
   activateContext,
+  assertServiceUrlForEnvironment,
+  assertTopoloServiceUrlEnvironment,
   clearProfileCredential,
   configPath,
   contextKey,
@@ -500,6 +728,7 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   resolveServiceUrls,
   resolvedProfileConfig,
   selectedEnvironment,
+  topoloServiceOrigins,
   writeConfig,
   writeContextCredential,
   writeProfileConfig

package/dist/node/credential-store.d.cts

@@ -20,6 +20,11 @@ type TopoloCredential = {
     expiresAt?: number;
 };
 
+declare const TOPOLO_RUNTIME_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
+type TopoloRuntimeEnvironment = (typeof TOPOLO_RUNTIME_ENVIRONMENTS)[number];
+declare function assertTopoloServiceUrlEnvironment(service: string, value: string, environment: TopoloRuntimeEnvironment): string;
+declare function topoloServiceOrigins(serviceUrls: Record<string, string> | undefined, environment: TopoloRuntimeEnvironment): Record<string, string>;
+
 /**
  * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
  *
@@ -33,7 +38,8 @@ type TopoloCredential = {
  * back to the on-disk credential when no `TOPOLO_*` env credential is set.
  */
 declare const TOPOLO_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
-type TopoloEnvironment = (typeof TOPOLO_ENVIRONMENTS)[number];
+type TopoloEnvironment = TopoloRuntimeEnvironment;
+
 interface TopoloConfig {
     credential?: TopoloCredential;
     /** OAuth client_id used for the most recent login — needed to refresh the access token. */
@@ -75,7 +81,7 @@ declare function contextKey(contextType: 'personal' | 'organization', organizati
  * local dev loop points services at ad-hoc ports, so it is driven entirely by
  * `TOPOLO_LOCAL_SERVICE_URL_*` / `TOPOLO_SERVICE_URL_*` overrides.
  */
-declare const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<TopoloEnvironment, Record<string, string>>;
+declare const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<"production" | "staging" | "development" | "local", Record<string, string>>;
 declare function configPath(): string;
 declare function readConfig(): Promise<TopoloConfig>;
 declare function writeConfig(config: TopoloConfig): Promise<void>;
@@ -109,6 +115,7 @@ declare function refreshContextCredentialIfNeeded(environment: TopoloEnvironment
 }): Promise<TopoloCredential | null>;
 declare function resolveAgentName(configAgentName?: string): string | undefined;
 declare function resolveServiceUrls(configUrls?: Record<string, string>, environment?: TopoloEnvironment): Record<string, string> | undefined;
+declare function assertServiceUrlForEnvironment(service: string, serviceUrl: string | undefined, environment?: TopoloEnvironment): void;
 declare function resolvedProfileConfig(config: TopoloConfig, environment?: TopoloEnvironment): TopoloEnvironmentProfile;
 
-export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, writeConfig, writeContextCredential, writeProfileConfig };
+export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, assertServiceUrlForEnvironment, assertTopoloServiceUrlEnvironment, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeProfileConfig };

package/dist/node/credential-store.d.ts

@@ -20,6 +20,11 @@ type TopoloCredential = {
     expiresAt?: number;
 };
 
+declare const TOPOLO_RUNTIME_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
+type TopoloRuntimeEnvironment = (typeof TOPOLO_RUNTIME_ENVIRONMENTS)[number];
+declare function assertTopoloServiceUrlEnvironment(service: string, value: string, environment: TopoloRuntimeEnvironment): string;
+declare function topoloServiceOrigins(serviceUrls: Record<string, string> | undefined, environment: TopoloRuntimeEnvironment): Record<string, string>;
+
 /**
  * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
  *
@@ -33,7 +38,8 @@ type TopoloCredential = {
  * back to the on-disk credential when no `TOPOLO_*` env credential is set.
  */
 declare const TOPOLO_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
-type TopoloEnvironment = (typeof TOPOLO_ENVIRONMENTS)[number];
+type TopoloEnvironment = TopoloRuntimeEnvironment;
+
 interface TopoloConfig {
     credential?: TopoloCredential;
     /** OAuth client_id used for the most recent login — needed to refresh the access token. */
@@ -75,7 +81,7 @@ declare function contextKey(contextType: 'personal' | 'organization', organizati
  * local dev loop points services at ad-hoc ports, so it is driven entirely by
  * `TOPOLO_LOCAL_SERVICE_URL_*` / `TOPOLO_SERVICE_URL_*` overrides.
  */
-declare const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<TopoloEnvironment, Record<string, string>>;
+declare const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<"production" | "staging" | "development" | "local", Record<string, string>>;
 declare function configPath(): string;
 declare function readConfig(): Promise<TopoloConfig>;
 declare function writeConfig(config: TopoloConfig): Promise<void>;
@@ -109,6 +115,7 @@ declare function refreshContextCredentialIfNeeded(environment: TopoloEnvironment
 }): Promise<TopoloCredential | null>;
 declare function resolveAgentName(configAgentName?: string): string | undefined;
 declare function resolveServiceUrls(configUrls?: Record<string, string>, environment?: TopoloEnvironment): Record<string, string> | undefined;
+declare function assertServiceUrlForEnvironment(service: string, serviceUrl: string | undefined, environment?: TopoloEnvironment): void;
 declare function resolvedProfileConfig(config: TopoloConfig, environment?: TopoloEnvironment): TopoloEnvironmentProfile;
 
-export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, writeConfig, writeContextCredential, writeProfileConfig };
+export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, assertServiceUrlForEnvironment, assertTopoloServiceUrlEnvironment, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeProfileConfig };