@deployport/api-services-corelib 0.1.4 → 0.3.0

package/configurator/loader.node.ts

@@ -0,0 +1,240 @@
+// Node-only configuration loader. This module is selected via the
+// `#config-loader` package import when running under Node (see package.json
+// `imports`). It is NEVER bundled for the browser, so it may freely import
+// Node builtins. The browser gets `loader.browser.ts` instead.
+//
+// The resolution chain mirrors the Go corelib (configurator/config_files.go,
+// configurator/configurator.go): explicit config -> DEPLOYPORT_* env ->
+// ~/.deployport files (for the resolved profile) -> DefaultRegion.
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { parse as parseYAML } from "yaml";
+import {
+    type AccountScope,
+    type Config,
+    type DeployportConfig,
+    type GetEndpointOverride,
+    type LoadDefaultConfig,
+    DEFAULT_CREDENTIALS_FILE_PATH,
+    DEFAULT_PROFILE,
+    DEFAULT_REGION,
+    DEFAULT_SETTINGS_FILE_PATH,
+    ENV_ACCESS_KEY_ID,
+    ENV_PROFILE,
+    ENV_REGION,
+    ENV_SECRET_ACCESS_KEY,
+} from "./config.js";
+
+// --- Parsed file shapes (match the YAML the Go SDK reads/writes) ------------
+
+type AccountCredentials = {
+    accessKeyID?: string;
+    secretAccessKey?: string;
+};
+
+type ProfileCredentials = {
+    global?: AccountCredentials;
+    current?: AccountCredentials;
+};
+
+type CredentialsFile = {
+    profiles?: Record<string, ProfileCredentials | undefined>;
+};
+
+type ServiceSettings = {
+    endpoint?: { url?: string };
+};
+
+type ProfileSettings = {
+    region?: string;
+    services?: Record<string, ServiceSettings | undefined>;
+};
+
+type SettingsFile = {
+    profiles?: Record<string, ProfileSettings | undefined>;
+};
+
+// --- Public API -------------------------------------------------------------
+
+/**
+ * loadDefaultConfig resolves the DeployPort config using the full default
+ * chain, filling only values not already set explicitly: environment variables,
+ * then the default config files for the resolved profile, then DEFAULT_REGION
+ * as a last resort. Explicit values always win. Missing files are ignored;
+ * malformed files throw.
+ */
+export async function loadDefaultConfig(config?: Config): Promise<Config> {
+    const dp: DeployportConfig = { ...(config?.deployport ?? {}) };
+    const anonymous = dp.anonymous ?? false;
+    const scope: AccountScope = dp.accountScope ?? "auto";
+    const profile = resolveProfile(dp.profile);
+
+    // Credentials are treated as a unit: if the caller set either field
+    // explicitly, we do not auto-load them from env or files (mirrors Go's
+    // `Credentials == nil` gate).
+    const credsExplicit = dp.accessKeyID != null || dp.secretAccessKey != null;
+    if (!anonymous && !credsExplicit) {
+        const envKeyID = process.env[ENV_ACCESS_KEY_ID];
+        const envSecret = process.env[ENV_SECRET_ACCESS_KEY];
+        if (envKeyID || envSecret) {
+            // Env provides the credentials as a unit; files are skipped.
+            dp.accessKeyID = envKeyID ?? "";
+            dp.secretAccessKey = envSecret ?? "";
+        } else {
+            const credsFile = await loadCredentialsFile(credentialsPath(dp));
+            const acc = accountFor(credsFile, profile, scope);
+            if (acc && acc.accessKeyID) {
+                dp.accessKeyID = acc.accessKeyID;
+                dp.secretAccessKey = acc.secretAccessKey ?? "";
+            }
+        }
+    }
+
+    // Region: explicit -> env -> settings file -> default.
+    if (!dp.region) {
+        const envRegion = process.env[ENV_REGION];
+        if (envRegion) {
+            dp.region = envRegion;
+        }
+    }
+    if (!dp.region) {
+        const settingsFile = await loadSettingsFile(settingsPath(dp));
+        const region = regionFor(settingsFile, profile);
+        if (region) {
+            dp.region = region;
+        }
+    }
+    if (!dp.region) {
+        dp.region = DEFAULT_REGION;
+    }
+
+    return { ...config, deployport: dp };
+}
+
+/**
+ * getEndpointOverride reads `profiles.<profile>.services.<service>.endpoint.url`
+ * from the settings file, or "" if none is set. Lets a Node consumer (e.g. a
+ * CLI) pick a per-service endpoint while corelib stays service-agnostic.
+ */
+export async function getEndpointOverride(
+    service: string,
+    options?: { profile?: string; settingsFilePath?: string },
+): Promise<string> {
+    const profile = resolveProfile(options?.profile);
+    const settingsFile = await loadSettingsFile(
+        options?.settingsFilePath ? expandPath(options.settingsFilePath) : defaultSettingsPath(),
+    );
+    return endpointFor(settingsFile, profile, service);
+}
+
+// --- Resolution helpers (mirror Go) -----------------------------------------
+
+function resolveProfile(explicit?: string): string {
+    if (explicit) {
+        return explicit;
+    }
+    const fromEnv = process.env[ENV_PROFILE];
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return DEFAULT_PROFILE;
+}
+
+function accountFor(
+    file: CredentialsFile,
+    profile: string,
+    scope: AccountScope,
+): AccountCredentials | undefined {
+    const p = file.profiles?.[profile];
+    if (!p) {
+        return undefined;
+    }
+    switch (scope) {
+        case "global":
+            return p.global;
+        case "current":
+            return p.current;
+        default: // "auto"
+            return p.current ?? p.global;
+    }
+}
+
+function regionFor(file: SettingsFile, profile: string): string {
+    return file.profiles?.[profile]?.region ?? "";
+}
+
+function endpointFor(file: SettingsFile, profile: string, service: string): string {
+    return file.profiles?.[profile]?.services?.[service]?.endpoint?.url ?? "";
+}
+
+// --- File loading ------------------------------------------------------------
+
+async function loadCredentialsFile(path: string): Promise<CredentialsFile> {
+    return loadYamlFile<CredentialsFile>(path, "credentials");
+}
+
+async function loadSettingsFile(path: string): Promise<SettingsFile> {
+    return loadYamlFile<SettingsFile>(path, "settings");
+}
+
+async function loadYamlFile<T extends object>(path: string, kind: string): Promise<T> {
+    let data: string;
+    try {
+        data = await readFile(path, "utf8");
+    } catch (err) {
+        if (isNotFound(err)) {
+            return { profiles: {} } as T;
+        }
+        throw new Error(`failed to read ${kind} file: ${errMessage(err)}`);
+    }
+    try {
+        return (parseYAML(data) as T) ?? ({ profiles: {} } as T);
+    } catch (err) {
+        throw new Error(`failed to parse ${kind} file: ${errMessage(err)}`);
+    }
+}
+
+function isNotFound(err: unknown): boolean {
+    return (err as NodeJS.ErrnoException)?.code === "ENOENT";
+}
+
+function errMessage(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+}
+
+// --- Path resolution ---------------------------------------------------------
+
+function credentialsPath(dp: DeployportConfig): string {
+    return dp.credentialsFilePath
+        ? expandPath(dp.credentialsFilePath)
+        : defaultCredentialsPath();
+}
+
+function settingsPath(dp: DeployportConfig): string {
+    return dp.settingsFilePath ? expandPath(dp.settingsFilePath) : defaultSettingsPath();
+}
+
+function defaultCredentialsPath(): string {
+    return expandPath(DEFAULT_CREDENTIALS_FILE_PATH);
+}
+
+function defaultSettingsPath(): string {
+    return expandPath(DEFAULT_SETTINGS_FILE_PATH);
+}
+
+/** Expands a leading `~` and `$HOME`/`${HOME}` to the user's home directory. */
+function expandPath(path: string): string {
+    const home = homedir();
+    return path
+        .replace(/^~(?=\/|$)/, home)
+        .replace(/\$\{HOME\}/g, home)
+        .replace(/\$HOME/g, home);
+}
+
+// Compile-time guard: this variant must match the shared loader signatures so
+// `#config-loader` resolves identically in Node and the browser.
+const _loadDefaultConfig: LoadDefaultConfig = loadDefaultConfig;
+const _getEndpointOverride: GetEndpointOverride = getEndpointOverride;
+void _loadDefaultConfig;
+void _getEndpointOverride;

package/configurator/loader.test.ts

@@ -0,0 +1,243 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getEndpointOverride, loadDefaultConfig } from "./loader.node.js";
+import { loadDefaultConfig as browserLoadDefaultConfig } from "./loader.browser.js";
+
+// Mirrors api-services-corelib-go/configurator/config_files_test.go.
+
+const sampleCredentialsYAML = `profiles:
+  default:
+    current:
+      accessKeyID: AKcurrent
+      secretAccessKey: SKcurrent
+    global:
+      accessKeyID: AKglobal
+      secretAccessKey: SKglobal
+`;
+
+const sampleSettingsYAML = `profiles:
+  default:
+    region: ljnyc
+    services:
+      iam: {}
+      binara:
+        endpoint:
+          url: https://ljb.deployport.io
+`;
+
+const ENV_KEYS = [
+    "HOME",
+    "DEPLOYPORT_ACCESS_KEY_ID",
+    "DEPLOYPORT_SECRET_ACCESS_KEY",
+    "DEPLOYPORT_REGION",
+    "DEPLOYPORT_PROFILE",
+] as const;
+
+let savedEnv: Record<string, string | undefined>;
+let tmpDirs: string[];
+
+beforeEach(() => {
+    savedEnv = {};
+    for (const k of ENV_KEYS) {
+        savedEnv[k] = process.env[k];
+    }
+    tmpDirs = [];
+    // Start every test from a known state.
+    delete process.env.DEPLOYPORT_ACCESS_KEY_ID;
+    delete process.env.DEPLOYPORT_SECRET_ACCESS_KEY;
+    delete process.env.DEPLOYPORT_REGION;
+    delete process.env.DEPLOYPORT_PROFILE;
+});
+
+afterEach(() => {
+    for (const k of ENV_KEYS) {
+        if (savedEnv[k] === undefined) {
+            delete process.env[k];
+        } else {
+            process.env[k] = savedEnv[k];
+        }
+    }
+    for (const d of tmpDirs) {
+        rmSync(d, { recursive: true, force: true });
+    }
+});
+
+function newTmpDir(): string {
+    const d = mkdtempSync(join(tmpdir(), "dpp-cfg-"));
+    tmpDirs.push(d);
+    return d;
+}
+
+// Writes credentials.yml and settings.yml under a fresh HOME/.deployport and
+// points HOME at it, so the default file paths resolve there.
+function writeConfigFiles(cred: string, settings: string): void {
+    const home = newTmpDir();
+    const dir = join(home, ".deployport");
+    mkdirSync(dir, { recursive: true });
+    if (cred) {
+        writeFileSync(join(dir, "credentials.yml"), cred);
+    }
+    if (settings) {
+        writeFileSync(join(dir, "settings.yml"), settings);
+    }
+    process.env.HOME = home;
+}
+
+describe("loadDefaultConfig (Node)", () => {
+    test("resolves credentials (auto -> current) and region from files", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        const c = await loadDefaultConfig();
+        expect(c.deployport?.accessKeyID).toBe("AKcurrent");
+        expect(c.deployport?.secretAccessKey).toBe("SKcurrent");
+        expect(c.deployport?.region).toBe("ljnyc");
+    });
+
+    test("account scope global selects the global account", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        const c = await loadDefaultConfig({ deployport: { accountScope: "global" } });
+        expect(c.deployport?.accessKeyID).toBe("AKglobal");
+    });
+
+    test("auto falls back to global when current is absent", async () => {
+        const globalOnly = `profiles:
+  default:
+    global:
+      accessKeyID: G
+      secretAccessKey: S
+`;
+        writeConfigFiles(globalOnly, "");
+        const c = await loadDefaultConfig();
+        expect(c.deployport?.accessKeyID).toBe("G");
+    });
+
+    test("env overrides file", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        process.env.DEPLOYPORT_ACCESS_KEY_ID = "AKenv";
+        process.env.DEPLOYPORT_SECRET_ACCESS_KEY = "SKenv";
+        process.env.DEPLOYPORT_REGION = "us-env-1";
+        const c = await loadDefaultConfig();
+        expect(c.deployport?.accessKeyID).toBe("AKenv");
+        expect(c.deployport?.region).toBe("us-env-1");
+    });
+
+    test("explicit wins over env and file", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        process.env.DEPLOYPORT_ACCESS_KEY_ID = "AKenv";
+        process.env.DEPLOYPORT_SECRET_ACCESS_KEY = "SKenv";
+        process.env.DEPLOYPORT_REGION = "us-env-1";
+        const c = await loadDefaultConfig({
+            deployport: {
+                accessKeyID: "AKexplicit",
+                secretAccessKey: "SKexplicit",
+                region: "explicit-region",
+            },
+        });
+        expect(c.deployport?.accessKeyID).toBe("AKexplicit");
+        expect(c.deployport?.region).toBe("explicit-region");
+    });
+
+    test("no source -> DefaultRegion, no credentials", async () => {
+        writeConfigFiles("", ""); // fresh empty HOME, no files
+        const c = await loadDefaultConfig();
+        expect(c.deployport?.region).toBe("us-east-2");
+        expect(c.deployport?.accessKeyID).toBeUndefined();
+    });
+
+    test("custom file paths", async () => {
+        const dir = newTmpDir();
+        const credPath = join(dir, "creds.yml");
+        const setPath = join(dir, "sets.yml");
+        writeFileSync(credPath, sampleCredentialsYAML);
+        writeFileSync(setPath, sampleSettingsYAML);
+        process.env.HOME = newTmpDir(); // empty home so defaults resolve to nothing
+        const c = await loadDefaultConfig({
+            deployport: { credentialsFilePath: credPath, settingsFilePath: setPath },
+        });
+        expect(c.deployport?.accessKeyID).toBe("AKcurrent");
+        expect(c.deployport?.region).toBe("ljnyc");
+    });
+
+    test("anonymous skips credential auto-loading but still resolves region", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        process.env.DEPLOYPORT_ACCESS_KEY_ID = "AKenv";
+        process.env.DEPLOYPORT_SECRET_ACCESS_KEY = "SKenv";
+        const c = await loadDefaultConfig({ deployport: { anonymous: true } });
+        expect(c.deployport?.accessKeyID).toBeUndefined();
+        expect(c.deployport?.region).toBe("ljnyc");
+    });
+
+    test("profile selection", async () => {
+        const cred = `profiles:
+  other:
+    current:
+      accessKeyID: AKother
+      secretAccessKey: SKother
+`;
+        const settings = `profiles:
+  other:
+    region: other-region
+`;
+        writeConfigFiles(cred, settings);
+        const c = await loadDefaultConfig({ deployport: { profile: "other" } });
+        expect(c.deployport?.accessKeyID).toBe("AKother");
+        expect(c.deployport?.region).toBe("other-region");
+    });
+
+    test("profile from DEPLOYPORT_PROFILE env", async () => {
+        const cred = `profiles:
+  other:
+    current:
+      accessKeyID: AKother
+      secretAccessKey: SKother
+`;
+        writeConfigFiles(cred, "");
+        process.env.DEPLOYPORT_PROFILE = "other";
+        const c = await loadDefaultConfig();
+        expect(c.deployport?.accessKeyID).toBe("AKother");
+    });
+
+    test("malformed file throws", async () => {
+        writeConfigFiles("profiles: [unterminated", "");
+        await expect(loadDefaultConfig()).rejects.toThrow(/failed to parse credentials file/);
+    });
+});
+
+describe("getEndpointOverride (Node)", () => {
+    test("reads a per-service endpoint override", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        expect(await getEndpointOverride("binara")).toBe("https://ljb.deployport.io");
+    });
+
+    test("service present but no override -> empty", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        expect(await getEndpointOverride("iam")).toBe("");
+    });
+
+    test("unknown service / missing file -> empty", async () => {
+        writeConfigFiles(sampleCredentialsYAML, sampleSettingsYAML);
+        expect(await getEndpointOverride("unknown-service")).toBe("");
+        process.env.HOME = newTmpDir(); // no settings file
+        expect(await getEndpointOverride("binara")).toBe("");
+    });
+});
+
+describe("loadDefaultConfig (browser stub)", () => {
+    test("passes explicit config through unchanged", async () => {
+        const input = {
+            deployport: { region: "eu-west-1", accessKeyID: "AK", secretAccessKey: "SK" },
+        };
+        expect(await browserLoadDefaultConfig(input)).toEqual(input);
+    });
+
+    test("does not fill any defaults (no env/file access)", async () => {
+        const c = await browserLoadDefaultConfig({ deployport: {} });
+        expect(c.deployport?.region).toBeUndefined();
+        expect(c.deployport?.accessKeyID).toBeUndefined();
+    });
+
+    test("handles undefined input", async () => {
+        expect(await browserLoadDefaultConfig()).toEqual({});
+    });
+});

package/configurator/signer.d.ts

@@ -1,15 +1,15 @@
 import { Runtime } from "@deployport/specular-runtime";
+import type { Config } from "./config.js";
 type Credentials = {
     keyID: string;
     secret: string;
 };
-export type Config = {
-    deployport?: {
-        region?: string;
-        accessKeyID?: string;
-        secretAccessKey?: string;
-    };
-};
+/**
+ * Replaces the `<region>` placeholder in the request URL and Host header with
+ * the given region. Mirrors Go's `ReplaceRegionInRequest`. Runs for every
+ * request that has a resolved region, whether or not the request is signed.
+ */
+export declare function replaceRegionInRequest(request: Runtime.HTTPRequest, region: string): void;
 export declare function ConfigureSignatureV1(submission: Runtime.Submission, config: Config): Promise<void>;
 export declare const getSigningKeyReal: (credentials: Credentials, shortDate: string, region: string, service: string, vendor: string) => Promise<Uint8Array>;
 /**

package/configurator/signer.js

@@ -1,40 +1,46 @@
 import { Sha256 } from '@aws-crypto/sha256-js';
-import { ServiceSignatureV1 } from '../specular.js';
+import { ServiceSignatureV1, SignedOperationV1 } from '../specular.js';
 const VendorCode = 'dpp';
+/**
+ * Replaces the `<region>` placeholder in the request URL and Host header with
+ * the given region. Mirrors Go's `ReplaceRegionInRequest`. Runs for every
+ * request that has a resolved region, whether or not the request is signed.
+ */
+export function replaceRegionInRequest(request, region) {
+    if (request.url) {
+        request.url = request.url.replaceAll("<region>", region);
+    }
+    const host = request.headers["Host"];
+    if (typeof host === "string") {
+        request.headers["Host"] = host.replaceAll("<region>", region);
+    }
+}
 export async function ConfigureSignatureV1(submission, config) {
-    // const { request } = submission;
-    // const { headers } = request;
-    // if (!headers["x-specular-signature"]) {
-    //     headers["x-specular-signature"] = "v1";
-    // }
-    console.log("Hello from ConfigureSignatureV1 in runtime/signer.ts!", submission);
+    // sign only operations that opted in via SignedOperationV1
+    const signedOperationV1 = submission.operation.annotations.find((a) => a instanceof SignedOperationV1);
+    if (!signedOperationV1) {
+        return;
+    }
     const annotations = submission.operation.resource.package.annotations;
-    console.log("service annotations", annotations);
     const serviceSignatureV1 = annotations.find((a) => a instanceof ServiceSignatureV1);
     if (!serviceSignatureV1) {
         return;
     }
-    console.log("signing using config", config);
     const { deployport } = config;
     if (!deployport) {
-        console.warn("missing required deployport configuration for signing", config);
         return;
     }
     const { region, accessKeyID: keyID, secretAccessKey: secret } = deployport;
     if (!region || !keyID || !secret) {
-        console.warn("missing required configuration for signing", deployport);
+        // Incomplete credentials/region: leave the request unsigned.
         return;
     }
     const { ServiceName: signingService } = serviceSignatureV1;
-    console.log("annotations", annotations, VendorCode, signingService);
     const { longDate, shortDate } = formatDate(new Date());
     const signingScope = buildSigningScope(VendorCode, region, signingService, shortDate);
-    console.log("signingScope", signingScope);
     const credentialPart = buildCredentialPart(keyID, signingScope);
-    console.log("credentialPart", credentialPart);
     const authHeaderPrefix = vendorAlgorithm(VendorCode) + " " + credentialPart;
     const bodyDigest = toHex(await hashSHA256(submission.request.body));
-    console.log("bodyDigest", bodyDigest);
     const headers = submission.request.headers;
     headers[vendorDateHeaderKey(VendorCode)] = longDate;
     headers[vendorHeaderCanonicalNameKey(VendorCode, "Service")] = signingService;
@@ -42,7 +48,6 @@ export async function ConfigureSignatureV1(submission, config) {
     headers[vendorHeaderCanonicalNameKey(VendorCode, "Operation")] = submission.operation.name;
     headers[vendorRegionHeaderKey(VendorCode)] = region;
     headers[vendorHeaderCanonicalNameKey(VendorCode, "Content-Sha256")] = bodyDigest;
-    console.log("headers", headers);
     const canonicalHeaders = getCanonicalHeaders(VendorCode, headers);
     const credentials = {
         keyID,
@@ -53,7 +58,6 @@ export async function ConfigureSignatureV1(submission, config) {
     // const payloadHash = await getPayloadHash(request.body);
     const signature = await getSignature(VendorCode, longDate, signingScope, signingKey, createCanonicalRequest(request, canonicalHeaders, bodyDigest));
     headers["Authorization"] = [authHeaderPrefix, `SignedHeaders=${canonicalHeaders.signedHeaders}`, `Signature=${signature}`];
-    console.log("signed headers", headers);
 }
 function createCanonicalRequest(request, canonicalHeaders, payloadHash) {
     const sortedHeaders = canonicalHeaders.names;
@@ -69,7 +73,6 @@ function getCanonicalQuery({ path }) {
     return ""; // TODO: hardcoded, we don't use query strings
 }
 function getCanonicalPath({ path }) {
-    console.log("getCanonicalPath path", path);
     return path;
     // if (this.uriEscapePath) {
     // Non-S3 services, we normalize the path and then double URI encode it.
@@ -95,7 +98,6 @@ function getCanonicalPath({ path }) {
     // For S3, we shouldn't normalize the path. For example, object name
     // my-object//example//photo.user should not be normalized to
     // my-object/example/photo.user
-    console.log("getCanonicalPath path (curated)", path);
     return path;
 }
 // /**
@@ -111,13 +113,11 @@ function getCanonicalPath({ path }) {
 // };
 async function getSignature(vendor, longDate, credentialScope, keyPromise, canonicalRequest) {
     const stringToSign = await createStringToSign(vendor, longDate, credentialScope, canonicalRequest);
-    console.log("stringToSign", stringToSign);
     const hash = new Sha256(await keyPromise);
     hash.update(stringToSign);
     return toHex(await hash.digest());
 }
 async function createStringToSign(vendor, longDate, credentialScope, canonicalRequest) {
-    console.log('canonicalRequest', canonicalRequest);
     const hash = new Sha256();
     hash.update(canonicalRequest);
     const hashedRequest = await hash.digest();

package/configurator/signer.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "vitest";
+import type { Runtime } from "@deployport/specular-runtime";
+import { replaceRegionInRequest } from "./signer.js";
+
+function req(url: string, headers: Record<string, string | string[]> = {}): Runtime.HTTPRequest {
+    return { url, headers } as unknown as Runtime.HTTPRequest;
+}
+
+describe("replaceRegionInRequest", () => {
+    test("substitutes <region> in the URL", () => {
+        const r = req("https://iam.<region>.api.deployport.io/api/User/List");
+        replaceRegionInRequest(r, "us-east-2");
+        expect(r.url).toBe("https://iam.us-east-2.api.deployport.io/api/User/List");
+    });
+
+    test("substitutes <region> in the Host header when present", () => {
+        const r = req("https://iam.<region>.api.deployport.io/api", {
+            Host: "iam.<region>.api.deployport.io",
+        });
+        replaceRegionInRequest(r, "eu-west-1");
+        expect(r.url).toBe("https://iam.eu-west-1.api.deployport.io/api");
+        expect(r.headers["Host"]).toBe("iam.eu-west-1.api.deployport.io");
+    });
+
+    test("leaves URLs without the placeholder unchanged", () => {
+        const r = req("https://iam.us-east-2.api.deployport.io/api");
+        replaceRegionInRequest(r, "us-east-2");
+        expect(r.url).toBe("https://iam.us-east-2.api.deployport.io/api");
+    });
+});