@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/sfcc/register.js

@@ -5,10 +5,32 @@
  * SFCC tools with a single call adjacent to `registerConductorTools`. All
  * SFCC business logic lives inside the sfcc/ module; index.ts stays a
  * thin registration/composition layer.
+ *
+ * ---------------------------------------------------------------------------
+ * Two structural properties this module owns (BAPI-817)
+ * ---------------------------------------------------------------------------
+ *
+ * **1. The target boundary is unavoidable.** The raw host registrar is used in
+ * exactly one place — `registerSfccTool`, the adapter below — and every other
+ * registration in this module and in every child registrar goes through that
+ * adapter. So the resolved-hostname sandbox check runs for all twenty tools:
+ * the two always-on diagnostics, the eight reads (including the five with no
+ * `instance` parameter at all), the nine writes, and `sfcc_log_query`. Asking
+ * each handler to remember a check is what produced the unguarded reads in the
+ * first place; wrapping the registrar removes the opportunity to forget.
+ *
+ * **2. Reads and writes are separately gated.** Before BAPI-817 one boolean
+ * (`includeReadTools`, from `ACTIVE_GROUPS.has("sfcc")`) registered eighteen
+ * tools, nine of them destructive — while the README described the group as
+ * "the 7 heavy SFCC read tools" and stated "All SFCC tools are read-only".
+ * Enabling introspection silently enabled mutation. This module now takes two
+ * independent flags so the `sfcc` profile is genuinely read-oriented and the
+ * nine writes require the deliberate `sfcc-write` opt-in (the ticket's
+ * Decision 2(c)).
  */
 import { z } from "zod";
 import { buildSfccSetupStatusHandler } from "./setup-status.js";
-import { withSfccGate } from "./tool-wrapper.js";
+import { withSfccGate, withSfccTargetBoundary } from "./tool-wrapper.js";
 import { checkPermissionsTool } from "./permissions.js";
 import { registerSystemObjectReadTools } from "./reads-system-object.js";
 import { registerSfccCustomObjectDefReadTools } from "./reads-custom-object-def.js";
@@ -22,7 +44,9 @@ import { registerSfccLogQueryTool } from "./log-query.js";
  * Register all SFCC tools through the host's registerTool wrapper.
  *
  * Call this once in index.ts, immediately after `registerConductorTools(registerTool)`.
- * Sub-task tickets (2–4) add their read tools here; they never touch index.ts.
+ * Read and write surfaces are selected independently by `deps.includeReadTools`
+ * and `deps.includeWriteTools`; the two always-on diagnostics register
+ * regardless. Every path goes through `registerSfccTool`.
  */
 export function registerSfccTools(registerTool, deps) {
     const gateDeps = {
@@ -30,8 +54,17 @@ export function registerSfccTools(registerTool, deps) {
         getGetHeaders: deps.getGetHeaders,
         repoName: deps.repoName,
     };
+    /**
+     * The one and only bridge between the host registrar and the SFCC surface.
+     *
+     * Every SFCC tool is registered through this, so every SFCC tool crosses the
+     * resolved-hostname boundary before its own handler runs. `registerTool` (the
+     * raw host registrar) must not be referenced anywhere else in this module or
+     * passed to a child registrar — `registration-boundary.test.ts` pins that.
+     */
+    const registerSfccTool = (name, config, handler) => registerTool(name, config, withSfccTargetBoundary(handler));
     // sfcc_setup_status — aggregate prerequisite reporter.
-    registerTool("sfcc_setup_status", {
+    registerSfccTool("sfcc_setup_status", {
         description: "Report on every SFCC prerequisite: Bridge API key, repo name, version config, " +
             "dw.json presence/uniqueness, and AM token acquisition. Always-registered; " +
             "returns status without requiring full SFCC configuration to be complete.",
@@ -40,53 +73,58 @@ export function registerSfccTools(registerTool, deps) {
     }, buildSfccSetupStatusHandler(deps.buildGetUrl, deps.getGetHeaders, deps.repoName, deps.getResolvedApiKey));
     // check_permissions — OCAPI access probe + settings JSON printer.
     const gatedCheckPermissions = withSfccGate(gateDeps, async (_args, credentials) => checkPermissionsTool(credentials));
-    registerTool("check_permissions", {
+    registerSfccTool("check_permissions", {
         description: "Probe SFCC OCAPI access via GET /system_object_definitions. " +
             "On 200: reports OK and the detected OCAPI version. " +
             "On 401/403: prints the exact OCAPI Settings JSON to paste in Business Manager " +
-            "(split read-only vs. write/import grants).",
+            "(read/search and mutation grants).",
         inputSchema: z.object({
             instance: z
                 .string()
+                .min(1)
                 .optional()
-                .describe("Explicit sandbox hostname to use instead of dw.json auto-detection."),
+                .describe("Sandbox hostname to use instead of dw.json. Still sandbox-validated."),
         }),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, gatedCheckPermissions);
-    // Heavy read tools are gated behind ACTIVE_GROUPS.has("sfcc") (BAPI-453).
-    // sfcc_setup_status and check_permissions above remain always-on (D-4 decision).
+    // The read profile — eight OCAPI reads plus sfcc_log_query — is gated behind
+    // ACTIVE_GROUPS.has("sfcc") (BAPI-453). sfcc_setup_status and
+    // check_permissions above remain always-on (D-4 decision).
     if (deps.includeReadTools) {
         // system_object_list, system_object_get, system_object_attribute_search (BAPI-401 T1–T3)
-        registerSystemObjectReadTools(registerTool, {
+        registerSystemObjectReadTools(registerSfccTool, {
             gateDeps,
             getDocsDir: deps.getDocsDir,
         });
         // custom_object_definition_attributes_get, custom_object_definition_attribute_search (BAPI-402 T4–T5)
-        registerSfccCustomObjectDefReadTools(registerTool, {
-            gateDeps,
-            getDocsDir: deps.getDocsDir,
-        });
-        // site_preference_get, site_preference_search (BAPI-403 T6 — optional)
-        registerSitePreferenceTools(registerTool, {
+        registerSfccCustomObjectDefReadTools(registerSfccTool, {
             gateDeps,
             getDocsDir: deps.getDocsDir,
         });
-        // SFCC write registration seam (BAPI-582). No write tools ship yet — future
-        // write-surface tickets register here. Gated behind the same includeReadTools
-        // branch so writes become default-on with reads whenever the sfcc profile
-        // group is active.
-        registerSfccWriteTools(registerTool, {
+        // site_preference_group_list, site_preference_get, site_preference_search (BAPI-403 T6)
+        registerSitePreferenceTools(registerSfccTool, {
             gateDeps,
             getDocsDir: deps.getDocsDir,
         });
         // sfcc_log_query (BAPI-556 T7) — gated, on-demand redacted/filtered log query.
-        // Uses its OWN call-time gate (log capability = WebDAV Basic auth), NOT the
-        // OCAPI version/dw.json/AM-token gate above.
-        registerSfccLogQueryTool(registerTool, {
+        // Uses its OWN call-time capability gate (log capability = WebDAV Basic
+        // auth), NOT the OCAPI version/dw.json/AM-token gate above. It is read-only,
+        // so it belongs to the read profile.
+        registerSfccLogQueryTool(registerSfccTool, {
             buildGetUrl: deps.buildGetUrl,
             getGetHeaders: deps.getGetHeaders,
             getPostHeaders: deps.getPostHeaders,
             repoName: deps.repoName,
         });
     }
+    // The nine destructive write tools are gated INDEPENDENTLY, behind
+    // ACTIVE_GROUPS.has("sfcc-write") (BAPI-817). This branch is deliberately not
+    // nested inside the read branch: `sfcc-write` alone is a valid selection, and
+    // `sfcc` alone must never register a tool carrying WRITE_ANNOTATIONS.
+    if (deps.includeWriteTools) {
+        registerSfccWriteTools(registerSfccTool, {
+            gateDeps,
+            getDocsDir: deps.getDocsDir,
+        });
+    }
 }

package/build/sfcc/registration-inventory.js

@@ -0,0 +1,89 @@
+/**
+ * Canonical inventory of every SFCC MCP tool name, by registration mode
+ * (BAPI-816).
+ *
+ * `register.ts` (`registerSfccTools`) decides WHICH tools register; this
+ * module is the single readable description of what that decision produces.
+ * Registrar tests compare captured registrations against these composed
+ * arrays instead of independently maintained numeric pins, which is exactly
+ * what let `register-site-preference.integration.test.ts` pin a stale `10`
+ * while the real registrar had already grown to 20 — a full write surface's
+ * worth of drift that no test caught (BAPI-816).
+ *
+ * `includeReadTools` is the legacy `SfccHostDeps` flag name (`register.ts`).
+ * Since BAPI-817 it gates the READ profile only — the eight OCAPI reads plus
+ * the log-query tool — while `includeWriteTools` independently gates the nine
+ * writes. The name predates both surfaces and was kept for call-site stability.
+ */
+import { SFCC_WRITE_TOOL_NAMES } from "./writes.js";
+/**
+ * Registered unconditionally, regardless of `includeReadTools` (D-4 decision
+ * in register.ts): the aggregate prerequisite reporter and the OCAPI access
+ * probe.
+ */
+export const SFCC_ALWAYS_REGISTERED_TOOL_NAMES = [
+    "sfcc_setup_status",
+    "check_permissions",
+];
+/**
+ * The eight read tools registered by the three read-module registrars
+ * (`registerSystemObjectReadTools`, `registerSfccCustomObjectDefReadTools`,
+ * `registerSitePreferenceTools`) when `includeReadTools` is true.
+ */
+export const SFCC_READ_TOOL_NAMES = [
+    "system_object_list",
+    "system_object_get",
+    "system_object_attribute_search",
+    "custom_object_definition_attributes_get",
+    "custom_object_definition_attribute_search",
+    "site_preference_group_list",
+    "site_preference_get",
+    "site_preference_search",
+];
+/** The on-demand redacted/filtered log-query tool (BAPI-556 T7). */
+export const SFCC_LOG_QUERY_TOOL_NAME = "sfcc_log_query";
+/**
+ * The `sfcc` READ profile: the eight OCAPI reads plus the log-query tool
+ * (BAPI-817).
+ *
+ * This is the exact set `includeReadTools` registers. Every member is read-only
+ * and carries read-only annotations; by construction no tool annotated
+ * `WRITE_ANNOTATIONS` can appear here, which is what makes "enabling `sfcc`
+ * cannot enable a mutation" checkable rather than merely intended.
+ */
+export const SFCC_READ_PROFILE_TOOL_NAMES = [
+    ...SFCC_READ_TOOL_NAMES,
+    SFCC_LOG_QUERY_TOOL_NAME,
+];
+/**
+ * The `sfcc-write` WRITE profile: the nine destructive tools (BAPI-817).
+ *
+ * Reused from `writes.ts#SFCC_WRITE_TOOL_NAMES` rather than duplicated, so the
+ * profile inventory and the registrar's own list cannot drift apart.
+ */
+export const SFCC_WRITE_PROFILE_TOOL_NAMES = [
+    ...SFCC_WRITE_TOOL_NAMES,
+];
+/**
+ * Every profile-gated tool, across both groups.
+ *
+ * Retained as the aggregate for consumers that care about "gated vs always-on"
+ * rather than which group gates it — but composed from the two profile
+ * inventories above, never hand-maintained. Order matches registration order in
+ * `register.ts`: the read branch runs first, then the write branch.
+ */
+export const SFCC_PROFILE_GATED_TOOL_NAMES = [
+    ...SFCC_READ_PROFILE_TOOL_NAMES,
+    ...SFCC_WRITE_PROFILE_TOOL_NAMES,
+];
+/**
+ * The complete SFCC registration surface: always-on plus both gated profiles.
+ *
+ * This is the twenty-tool surface a `BRIDGE_MCP_PROFILE=sfcc,sfcc-write` (or
+ * `full`) session exposes, and the iteration source for the boundary-coverage
+ * test — so a newly added tool cannot silently evade that coverage.
+ */
+export const SFCC_ALL_REGISTERED_TOOL_NAMES = [
+    ...SFCC_ALWAYS_REGISTERED_TOOL_NAMES,
+    ...SFCC_PROFILE_GATED_TOOL_NAMES,
+];

package/build/sfcc/setup-status.js

@@ -6,7 +6,6 @@
  * prevent the others from running.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
-import { resolveSfccCredentials } from "./credentials.js";
 import { getAmToken } from "./client.js";
 // ---------------------------------------------------------------------------
 // Implementation
@@ -57,39 +56,20 @@ export async function sfccSetupStatusTool(deps) {
         versionStatus = "— Skipped (Bridge API not configured)";
     }
     lines.push(`3. SFCC Version: ${versionStatus}`);
-    // 4. dw.json / credential resolution
-    let credStatus = "✗ Missing";
-    let resolvedCredentials = null;
-    try {
-        const result = await resolveSfccCredentials();
-        if (result.ok) {
-            // Report source and instance ID only — never the secret values.
-            resolvedCredentials = {
-                hostname: result.credentials.hostname.split(".")[0] ?? result.credentials.hostname,
-                source: result.credentials.source,
-            };
-            credStatus = `✓ Found (${resolvedCredentials.source})`;
-        }
-        else {
-            credStatus = `✗ ${result.error}`;
-        }
-    }
-    catch (err) {
-        credStatus = `✗ Resolution error: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    lines.push(`4. dw.json / Credentials: ${credStatus}`);
-    // 5. AM token acquisition (only if credentials were resolved)
+    // 4. dw.json / credential resolution — read from the boundary-approved target
+    // rather than resolved again here (BAPI-817).
+    const target = deps.target;
+    // Report source and instance ID only — never the secret values.
+    const instanceLabel = target.approved
+        ? target.hostname.split(".")[0] ?? target.hostname
+        : null;
+    lines.push(`4. dw.json / Credentials: ${target.approved ? `✓ Found (${target.credentials.source})` : `✗ ${target.error}`}`);
+    // 5. AM token acquisition (only when the boundary approved a target).
     let tokenStatus = "— Skipped (credentials not available)";
-    if (resolvedCredentials) {
+    if (target.approved) {
         try {
-            const credResult = await resolveSfccCredentials();
-            if (credResult.ok) {
-                await getAmToken(credResult.credentials);
-                tokenStatus = `✓ Token acquired for instance ${resolvedCredentials.hostname}`;
-            }
-            else {
-                tokenStatus = "✗ Credentials not resolved";
-            }
+            await getAmToken(target.credentials);
+            tokenStatus = `✓ Token acquired for instance ${instanceLabel}`;
         }
         catch (err) {
             // Sanitize: strip any token/secret-looking content from error message.
@@ -135,10 +115,14 @@ export async function sfccSetupStatusTool(deps) {
 }
 /**
  * Build the sfcc_setup_status handler bound to the host's runtime deps.
+ *
+ * The returned handler takes the `SfccTargetContext` the registration-level
+ * sandbox boundary supplies (BAPI-817) and forwards it, so this tool reports on
+ * the same target the boundary approved and never resolves one of its own.
  */
 export function buildSfccSetupStatusHandler(buildGetUrl, getGetHeaders, repoName, getApiKey) {
-    return async (_args) => {
+    return async (_args, target) => {
         const apiKey = await getApiKey();
-        return sfccSetupStatusTool({ buildGetUrl, getGetHeaders, repoName, apiKey });
+        return sfccSetupStatusTool({ buildGetUrl, getGetHeaders, repoName, apiKey, target });
     };
 }

package/build/sfcc/tool-wrapper.js

@@ -1,19 +1,290 @@
 /**
- * Call-time SFCC configuration gate.
+ * The SFCC target boundary and the call-time SFCC configuration gate.
  *
- * Wraps every SFCC tool handler. Evaluated at call time (NOT startup) so all
- * SFCC tools are always registered — the gate decides at invocation whether the
- * repo is configured for SFCC and has valid local credentials.
+ * This module owns two distinct, layered checks. They run in this order, and
+ * the order is the whole point:
+ *
+ *   1. `withSfccTargetBoundary` — WHICH INSTANCE are we about to contact?
+ *      Resolves credentials through the real precedence chain and validates the
+ *      hostname those credentials actually select. Fails closed.
+ *   2. `withSfccGate` — is this repo CONFIGURED for SFCC at all? Reads the
+ *      Bridge `version` config field and consumes the already-approved target
+ *      rather than resolving a second time.
  *
  * The "not configured" response distinguishes three failure classes:
  *   (a) Bridge-auth/config failure — could not read /config-field/version.
  *   (b) version-not-SFCC — version is set but is not an SFCC version.
  *   (c) missing/ambiguous dw.json — credential resolution failed.
+ *
+ * ---------------------------------------------------------------------------
+ * DECISION 1(a) — validate the RESOLVED hostname (BAPI-817)
+ * ---------------------------------------------------------------------------
+ *
+ * The README promised in five places that "non-sandbox instances are rejected".
+ * Before BAPI-817 nothing validated the target host. The only two guards
+ * (`write-guard.ts`, `reads-site-preference.ts`) compared a CALLER-SUPPLIED
+ * string argument to the literal `"sandbox"` — and `write-guard.ts` defaulted an
+ * omitted `instance` to `"sandbox"`, so the guard passed on its single most
+ * common call shape while the request went to whatever host `dw.json` named.
+ * Point `dw.json` or `SFCC_HOSTNAME` at production and every read and all nine
+ * writes executed against it.
+ *
+ * BAPI-817 resolves the ticket's Decision 1 as **(a): validate the actual
+ * resolved target hostname**, not (b) per-instance opt-in. (a) is the fix that
+ * makes the existing documentation true rather than lowering the promise to
+ * match the code. Two properties make it load-bearing:
+ *
+ *   - **It validates `credentials.hostname`**, the value the OCAPI client will
+ *     literally put in the URL — never `args.instance`, never `SFCC_HOSTNAME`,
+ *     never a raw `dw.json` field read independently. Every credential
+ *     precedence tier converges on one resolved host, so validating that one
+ *     value covers all of them. A check on any input *upstream* of resolution
+ *     can be contradicted by a later tier; a check on the output cannot.
+ *   - **It fails closed.** An unrecognized, malformed, or unparseable hostname
+ *     is refused. The accepted forms are an anchored allowlist built only from
+ *     hostname forms this repository actually evidences (see
+ *     `APPROVED_SANDBOX_HOST_FORMS`); a substring test such as
+ *     `hostname.includes(".sandbox.")` is NOT used, because it also matches
+ *     hosts like `prod.sandbox.attacker.example` where the label is not in the
+ *     position the form requires.
+ *
+ * Caller-supplied context can no longer authorize a target. Omitting `instance`
+ * and passing `instance: "sandbox"` are now equivalent to passing nothing: they
+ * do not enter the decision. A dotted `instance` still *selects* a host through
+ * the existing explicit-override precedence, but the host it selects is then
+ * validated like any other, so `check_permissions` can no longer be aimed at an
+ * arbitrary named production instance.
+ *
+ * `register.ts` makes this structurally unavoidable: it wraps the host
+ * registrar once, and every SFCC tool — the always-on diagnostics, the eight
+ * reads (including the five that have no `instance` parameter at all), the nine
+ * writes, and `sfcc_log_query` — is registered through that adapter. There is
+ * no per-tool opt-in and no exemption flag.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
 import { resolveSfccCredentials } from "./credentials.js";
 import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
+// Hostname policy
+// ---------------------------------------------------------------------------
+/**
+ * The DNS suffix every approved sandbox form shares.
+ *
+ * Every SFCC developer-sandbox hostname evidenced anywhere in this repository —
+ * `credentials.ts`'s JSDoc, the install guide's prerequisites, the BAPI-399
+ * live smoke-test record, and the existing test fixtures — lives under this
+ * suffix. Legacy `*.demandware.net` hosts are deliberately NOT accepted: that
+ * domain covers sandbox, staging, development, and production instances alike
+ * with no suffix that separates them, so admitting it would reintroduce exactly
+ * the unbounded target this boundary exists to close. It appears in this repo
+ * only as a test fixture, never in production code or the SFCC install docs.
+ */
+const SFCC_DX_SUFFIX = ".dx.commercecloud.salesforce.com";
+/**
+ * First labels that name a non-sandbox environment on the B2C platform.
+ *
+ * Checked against the leading label of every candidate, so a host like
+ * `production-zzrf.dx.commercecloud.salesforce.com` or
+ * `staging-zzrf.sandbox.us01.dx.commercecloud.salesforce.com` is refused even
+ * though it would otherwise satisfy a form below. This is belt-and-braces: form
+ * B alone would already admit `production-001`, and a named production instance
+ * is precisely the target the ticket was filed about.
+ */
+const RESERVED_ENVIRONMENT_LABELS = [
+    "production",
+    "prod",
+    "staging",
+    "stg",
+    "development",
+];
+/**
+ * Human-readable description of every accepted form, for the refusal envelope
+ * and the documentation contract test. Keep in sync with
+ * `isApprovedSfccSandboxHost` — the tests assert both directions.
+ */
+export const APPROVED_SANDBOX_HOST_FORMS = [
+    "<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com",
+    "<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com",
+    "<realm>-<nnn>.dx.commercecloud.salesforce.com",
+];
+/** One DNS label: 1–63 chars, alphanumeric, internal hyphens only. */
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/** Form B's leading label: an SFCC realm id followed by a numeric instance. */
+const REALM_INSTANCE_LABEL = /^[a-z0-9]+-\d{3}$/;
+/**
+ * Reduce a raw hostname to a canonical comparable form, or `null` if it is not
+ * a bare hostname at all.
+ *
+ * Only DNS-equivalent normalization is applied — lowercasing and stripping a
+ * single trailing root dot. Everything else is a rejection rather than a
+ * repair: a value carrying a scheme, port, path, query, credentials, or
+ * whitespace is not a hostname, and "cleaning it up" would mean guessing which
+ * part the operator meant. Guessing is how a boundary gets bypassed, so this
+ * returns `null` and the caller fails closed.
+ */
+export function canonicalizeSfccHostname(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let value = raw.trim().toLowerCase();
+    if (value.endsWith("."))
+        value = value.slice(0, -1);
+    if (value === "" || value.length > 253)
+        return null;
+    // Anything that is not strictly `label(.label)*` — scheme, port, path, query,
+    // userinfo, whitespace, IPv6 brackets, wildcards.
+    if (!/^[a-z0-9.-]+$/.test(value))
+        return null;
+    if (value.includes(".."))
+        return null;
+    const labels = value.split(".");
+    if (labels.length < 2)
+        return null;
+    if (!labels.every((label) => DNS_LABEL.test(label)))
+        return null;
+    // A bare IPv4 address is not a sandbox hostname and must not be canonicalized
+    // into one; the suffix check below would reject it anyway, but rejecting here
+    // keeps "is this a hostname?" and "is this host approved?" separate concerns.
+    if (/^\d+(\.\d+)*$/.test(value))
+        return null;
+    return value;
+}
+/**
+ * Decide whether a canonical hostname is an approved developer sandbox.
+ *
+ * Matching is ANCHORED on both ends: the host must END with the platform suffix
+ * and the labels in front of it must form one of the shapes below. This is the
+ * property a substring test lacks —  `.includes(".sandbox.")` matches
+ * `zzzz-001.sandbox.evil.example.com`, whose registrable domain is not
+ * Salesforce's at all.
+ *
+ *   Form A — explicit sandbox label, with or without a region:
+ *     `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`
+ *     `zzzz-001.sandbox.dx.commercecloud.salesforce.com`
+ *   Form B — realm + numeric instance, the on-demand sandbox form this project
+ *     actually smoke-tested against (`docs/BAPI-399-sfcc-mcp-smoke-test.md`
+ *     records sandbox `zyis-001`):
+ *     `zyis-001.dx.commercecloud.salesforce.com`
+ *
+ * Form B is required for correctness, not convenience: without it the boundary
+ * would refuse the very sandbox this repository documents itself using, and a
+ * safety check that blocks the intended workflow gets disabled rather than
+ * obeyed. It is kept safe by requiring the `<realm>-<nnn>` shape (named
+ * environments such as `production-zzrf` do not match) and by the reserved-label
+ * check.
+ *
+ * Anything not matching — including every `*.demandware.net` host and any other
+ * registrable domain — is refused. Widening this set is a deliberate decision,
+ * not a bug fix: the ticket's Decision 1(b), an explicit per-instance opt-in, is
+ * the sanctioned way to reach an instance this policy does not recognize.
+ */
+export function isApprovedSfccSandboxHost(canonical) {
+    if (!canonical.endsWith(SFCC_DX_SUFFIX))
+        return false;
+    const prefix = canonical.slice(0, -SFCC_DX_SUFFIX.length);
+    if (prefix === "")
+        return false;
+    const labels = prefix.split(".");
+    const first = labels[0];
+    for (const reserved of RESERVED_ENVIRONMENT_LABELS) {
+        if (first === reserved || first.startsWith(`${reserved}-`))
+            return false;
+    }
+    // Form A: <label>.sandbox[.<region>]
+    if ((labels.length === 2 || labels.length === 3) && labels[1] === "sandbox")
+        return true;
+    // Form B: <realm>-<nnn>
+    if (labels.length === 1 && REALM_INSTANCE_LABEL.test(first))
+        return true;
+    return false;
+}
+/**
+ * The one refusal envelope every SFCC tool returns for an unapproved target.
+ *
+ * Built through the shared `formatSfccFailure` so it is detectable by
+ * `result.isError === true` and parseable by the single SFCC error-parse path,
+ * exactly like every other SFCC failure.
+ *
+ * `403` is the honest status: Bridge understood the request and refused to
+ * perform it. `source: "gate"` is likewise honest — this is Bridge's own
+ * decision, not something OCAPI or WebDAV returned, so no upstream status is
+ * supplied.
+ *
+ * Only the rejected hostname and the accepted forms appear in the body. The
+ * hostname is not a secret and the operator cannot fix the problem without
+ * seeing it; the credential source string, client id, client secret, token, and
+ * raw `dw.json` contents never enter this envelope.
+ */
+function targetNotSandbox(rejectedHostname) {
+    // A malformed value is echoed back bounded, so a pathological configuration
+    // value cannot inflate the response.
+    const safeRejected = rejectedHostname.length > 120 ? `${rejectedHostname.slice(0, 120)}…` : rejectedHostname;
+    return formatSfccFailure({
+        code: "TARGET_NOT_SANDBOX",
+        status: 403,
+        message: `SFCC tools are restricted to a developer sandbox. Refusing to contact ` +
+            `'${safeRejected}', which is not a recognized sandbox instance. Point dw.json ` +
+            `or SFCC_HOSTNAME at a developer sandbox and retry.`,
+        source: "gate",
+        details: {
+            failure_class: "target-not-sandbox",
+            rejected_hostname: safeRejected,
+            approved_hostname_forms: APPROVED_SANDBOX_HOST_FORMS,
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Target boundary
+// ---------------------------------------------------------------------------
+/**
+ * Wrap an SFCC handler with the resolved-hostname sandbox boundary.
+ *
+ * `register.ts` applies this to EVERY SFCC tool by wrapping the host registrar
+ * once, so no tool can be added that skips it — the alternative, asking each
+ * handler to remember a check, is what produced the five reads that had no
+ * `instance` parameter and therefore no guard at all.
+ *
+ * The returned handler:
+ *   1. Derives an explicit hostname override from `args.instance`, preserving
+ *      the existing "a hostname always contains a dot, the OCAPI instance-context
+ *      enum never does" rule.
+ *   2. Resolves credentials through the real precedence chain.
+ *   3. Refuses when the RESOLVED hostname is not an approved sandbox.
+ *   4. Otherwise calls the handler with the approved target.
+ *
+ * A resolution failure is passed through rather than refused — see
+ * `SfccTargetContext`. The refusal is returned as a normal MCP result and never
+ * thrown, so it cannot escape to the stdio transport.
+ */
+export function withSfccTargetBoundary(handler, deps = {}) {
+    const resolve = deps.resolveCredentials ?? resolveSfccCredentials;
+    return async (args) => {
+        const safeArgs = args ?? {};
+        // A hostname always contains a dot; the OCAPI instance-context enum
+        // (e.g. "sandbox") never does — only treat args.instance as an explicit
+        // hostname override when it looks like one. The override still only
+        // *selects* a candidate; approval below is based on what resolution
+        // actually returned.
+        const rawInstance = typeof safeArgs.instance === "string" ? safeArgs.instance : undefined;
+        const explicitHostname = rawInstance && rawInstance.includes(".") ? rawInstance : undefined;
+        const credResult = await resolve(explicitHostname);
+        if (!credResult.ok) {
+            return handler(safeArgs, { approved: false, error: credResult.error });
+        }
+        const rawHostname = credResult.credentials.hostname;
+        const canonical = canonicalizeSfccHostname(rawHostname);
+        if (canonical === null || !isApprovedSfccSandboxHost(canonical)) {
+            return targetNotSandbox(typeof rawHostname === "string" ? rawHostname : String(rawHostname));
+        }
+        return handler(safeArgs, {
+            approved: true,
+            // The canonical host is substituted so every downstream URL is built from
+            // the exact value that was approved.
+            credentials: { ...credResult.credentials, hostname: canonical },
+            hostname: canonical,
+        });
+    };
+}
+// ---------------------------------------------------------------------------
 // Not-configured envelope helpers
 // ---------------------------------------------------------------------------
 /**
@@ -71,14 +342,24 @@ function notConfigured(failureClass, message) {
  * The returned handler:
  * 1. Reads /config-field/version via Bridge API.
  * 2. Validates the value is an SFCC version.
- * 3. Resolves dw.json credentials.
+ * 3. Consumes the credentials the target boundary already approved.
  * 4. Calls the inner handler only if all checks pass.
  *
+ * **This gate no longer resolves credentials itself** (BAPI-817). It receives an
+ * `SfccTargetContext` that `withSfccTargetBoundary` produced, and uses the
+ * credentials in it. Resolving a second time here would let the gate hand a
+ * handler a *different* host than the one that was approved — a
+ * time-of-check/time-of-use split in the middle of the boundary this ticket
+ * exists to establish. `missing-dw-json` is still this gate's own failure class
+ * and keeps its exact prior envelope; it is now driven by the unresolved target
+ * context rather than by a duplicate resolution call.
+ *
  * Every early rejection is the unified `isError: true` result — unconditionally,
  * with no tool-name check, per-tool branch, exemption flag, or gate-mode
  * parameter. `sfcc_setup_status`, the one SFCC tool whose successful output *is*
  * a not-configured report, is exempt structurally: `register.ts` registers it
- * outside this gate, so no code here needs to know about it.
+ * outside this gate (though still inside the target boundary), so no code here
+ * needs to know about it.
  *
  * On the success path the inner handler's result is returned directly — not
  * cloned, wrapped, or re-formatted — so write handlers keep ownership of their
@@ -86,7 +367,7 @@ function notConfigured(failureClass, message) {
  * type through the gate.
  */
 export function withSfccGate(deps, handler) {
-    return async (args) => {
+    return async (args, target) => {
         // (a) Read /config-field/version
         const version = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
         if (version === null) {
@@ -100,18 +381,14 @@ export function withSfccGate(deps, handler) {
                 `Expected one of: ${SFCC_VERSIONS.join(", ")}. ` +
                 `Update the version field in your Bridge API project settings.`);
         }
-        // (c) Resolve credentials from dw.json
-        // A hostname always contains a dot; the OCAPI instance-context enum
-        // (e.g. "sandbox") never does — only treat args.instance as an explicit
-        // hostname override when it looks like one.
-        const rawInstance = typeof args.instance === "string" ? args.instance : undefined;
-        const explicitHostname = rawInstance && rawInstance.includes(".") ? rawInstance : undefined;
-        const credResult = await resolveSfccCredentials(explicitHostname);
-        if (!credResult.ok) {
-            return notConfigured("missing-dw-json", `SFCC credential resolution failed: ${credResult.error} ` +
+        // (c) Consume the boundary-approved target. An unapproved *host* never
+        // reaches here — the boundary already refused it — so the only remaining
+        // case is credential resolution having failed outright.
+        if (!target.approved) {
+            return notConfigured("missing-dw-json", `SFCC credential resolution failed: ${target.error} ` +
                 "Ensure a dw.json file exists in your project root with " +
                 "hostname, client-id, and client-secret fields.");
         }
-        return handler(args, credResult.credentials);
+        return handler(args, target.credentials);
     };
 }