@bridge_gpt/mcp-server 0.2.38 → 0.2.41

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);
     };
 }

package/build/sfcc/write-grants.js

@@ -27,6 +27,38 @@ export const OCAPI_WRITE_RESOURCE_IDS = [
     "/custom_object_definitions/**",
     "/site_preferences/**",
 ];
+/**
+ * The exact HTTP methods each resource family needs, derived from the methods
+ * the nine shipped write handlers actually call (BAPI-817).
+ *
+ * Previously every family was granted `["get","put","patch","delete"]`. **No
+ * shipped handler performs a DELETE** — the write surface is create/update only
+ * (`ocapiPut`, `ocapiPatch`, `ocapiPatchDirect` in `client.ts`; verified across
+ * `writes-system-object.ts`, `writes-custom-object-def.ts`, and
+ * `writes-site-preference.ts`). Granting `delete` handed an operator's OCAPI
+ * client a destructive capability that Bridge cannot even invoke, on a grant
+ * they were told to paste once and forget. The narrower set below is what the
+ * code demonstrably needs and nothing more.
+ *
+ * `get` is retained where a write path genuinely reads: `ocapiPatch` performs a
+ * GET-then-If-Match ETag round trip before the PATCH, so removing `get` would
+ * break every update tool.
+ *
+ *   /system_object_definitions       get   — the check_permissions probe.
+ *   /system_object_definitions/**    put, patch (+get for ETag) — attribute and
+ *                                    attribute-group create/update, assignment,
+ *                                    custom preference create.
+ *   /custom_object_definitions/**    put, patch (+get for ETag) — attribute
+ *                                    definition create/update.
+ *   /site_preferences/**             patch (+get) — site_preference_values_set,
+ *                                    a direct PATCH with no ETag round trip.
+ */
+export const OCAPI_WRITE_RESOURCE_METHODS = {
+    "/system_object_definitions": ["get"],
+    "/system_object_definitions/**": ["get", "put", "patch"],
+    "/custom_object_definitions/**": ["get", "put", "patch"],
+    "/site_preferences/**": ["get", "patch"],
+};
 // ---------------------------------------------------------------------------
 // Grant JSON builders
 // ---------------------------------------------------------------------------
@@ -44,7 +76,7 @@ export function buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder =
                 client_id: clientIdPlaceholder,
                 resources: OCAPI_WRITE_RESOURCE_IDS.map((resource_id) => ({
                     resource_id,
-                    methods: ["get", "put", "patch", "delete"],
+                    methods: [...(OCAPI_WRITE_RESOURCE_METHODS[resource_id] ?? [])],
                     read_attributes: "(**)",
                     write_attributes: "(**)",
                 })),

package/build/sfcc/write-guard.js

@@ -1,11 +1,36 @@
 /**
- * Reusable sandbox-only write guard (BAPI-582 foundation).
+ * Secondary OCAPI instance-CONTEXT check for writes (BAPI-582 foundation).
  *
- * Future SFCC write handlers MUST call `rejectIfNotSandboxForWrite`
- * immediately after input parsing and BEFORE any payload construction or OCAPI
- * mutation. A non-null return value is
- * the pre-formatted MCP rejection to return directly; a null return means the
- * effective instance is a sandbox and the handler may proceed.
+ * ⚠️ **This is NOT the sandbox security boundary.** It validates a
+ * caller-supplied *input string*, not the instance the request will reach. The
+ * hostname boundary lives in `tool-wrapper.ts`
+ * (`withSfccTargetBoundary` / `isApprovedSfccSandboxHost`), runs at
+ * registration level for all twenty SFCC tools, and validates the hostname
+ * credential resolution actually selected.
+ *
+ * The distinction is the entire subject of BAPI-817. This guard was previously
+ * described — in the README and in its own comments — as the thing that made
+ * SFCC writes sandbox-only. It never could be: `instance` is an argument the
+ * caller chooses, the target came from `dw.json`/`SFCC_HOSTNAME`, and the two
+ * were never compared. Worse, the guard **defaulted an omitted `instance` to
+ * `"sandbox"` and passed**, so it approved its single most common call shape
+ * while the request went to whatever host was configured. Nine destructive
+ * tools sat behind that.
+ *
+ * The behavior below is deliberately UNCHANGED, and is kept only as
+ * defence-in-depth on the OCAPI instance-context input: it rejects a caller who
+ * explicitly asks for `"staging"` or `"production"` context, which is still
+ * worth refusing. What changed is what it is allowed to *mean*. Its acceptance
+ * no longer authorizes anything — a write reaching this guard has already had
+ * its target hostname independently approved, and omitting `instance` cannot
+ * bypass that approval because the hostname check does not consult `instance`
+ * at all.
+ *
+ * SFCC write handlers still call `rejectIfNotSandboxForWrite` immediately after
+ * input parsing and BEFORE any payload construction or OCAPI mutation. A
+ * non-null return value is the pre-formatted MCP rejection to return directly;
+ * a null return means the effective instance context is `sandbox` and the
+ * handler may proceed.
  *
  * BAPI-766 moved the rejection's *representation* to the shared SFCC formatter
  * so the guardrail fails at the protocol level like every other SFCC failure.
@@ -17,13 +42,17 @@ import { formatSfccWriteFailure } from "./sfcc-result.js";
 // Guard
 // ---------------------------------------------------------------------------
 /**
- * Reject any write targeting a non-sandbox instance.
+ * Reject a write whose OCAPI instance CONTEXT is not `sandbox`.
+ *
+ * The effective context defaults to `"sandbox"` when `undefined` (some schemas
+ * default the value elsewhere), so an omitted instance is allowed here. That
+ * permissive default is safe only because it is no longer load-bearing: the
+ * resolved-hostname boundary has already approved the target before any handler
+ * runs, and it never consults this argument. Returning `null` therefore means
+ * "this input is not objectionable", never "this target is a sandbox".
  *
- * SFCC write tools are sandbox-only in this foundation. The effective instance
- * defaults to `"sandbox"` when `undefined` (some schemas default the value
- * elsewhere), so an omitted instance is allowed. Any other value returns the
- * unified validation failure naming the rejected instance; a sandbox returns
- * `null` so the caller proceeds.
+ * Any other value returns the unified validation failure naming the rejected
+ * context.
  *
  * `details` carries non-sensitive guard metadata only — the rejected value is
  * caller-supplied.

package/build/sfcc/writes-custom-object-def.js

@@ -28,8 +28,12 @@ import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpecte
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
-const INSTANCE_DESCRIBE = "OCAPI instance context. SFCC writes are sandbox-only; omit for sandbox. Any " +
-    "other value is rejected before OCAPI is called.";
+// OCAPI instance CONTEXT, not a target selector: the instance actually
+// contacted is decided by the resolved-hostname boundary (BAPI-817), which this
+// value cannot influence. "omit for sandbox" is gone because omitting it never
+// selected anything.
+const INSTANCE_DESCRIBE = "OCAPI instance context. Omit or pass \"sandbox\"; any other value is " +
+    "rejected before OCAPI is called.";
 const createCustomObjectAttributeDefinitionInput = z.object({
     object_type: z
         .string()

package/build/sfcc/writes-site-preference.js

@@ -28,8 +28,13 @@ import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpecte
 // Mirror reads-site-preference.ts so callers see the same instance enum, while
 // the write remains sandbox-only (enforced by the guard + the literal path).
 const INSTANCE_ENUM = z.enum(["staging", "development", "sandbox", "production"]);
+// OCAPI instance CONTEXT only. The trailing "Defaults to 'sandbox'" is gone:
+// it read as though the default selected a safe target, when the target is
+// decided by the resolved-hostname boundary (BAPI-817) and this value cannot
+// influence it. The forced `/sandbox` path segment below remains as an extra
+// safeguard on the OCAPI route.
 const INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; any other " +
-    "value is rejected before OCAPI is called. Defaults to 'sandbox'.";
+    "value is rejected before OCAPI is called.";
 const sitePreferenceValuesSetInput = z.object({
     group: z.string().describe("Custom site preference group id, e.g. 'LLMIntegration'."),
     instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),

package/build/sfcc/writes-system-object.js

@@ -50,11 +50,20 @@ function preferenceObjectTypeForScope(scope) {
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
-/** Optional sandbox instance context. Writes are sandbox-only (see write-guard). */
+/**
+ * Optional OCAPI instance CONTEXT — not a target selector.
+ *
+ * The old description ("Sandbox-only: omit (defaults to sandbox) or pass
+ * \"sandbox\"") told the model that omitting this field selected a sandbox. It
+ * never did: the host came from `dw.json`/`SFCC_HOSTNAME`, and omitting the
+ * field only made `write-guard.ts` default to `"sandbox"` and pass. Which
+ * instance is actually contacted is decided by the resolved-hostname boundary in
+ * `tool-wrapper.ts` (BAPI-817), which this value cannot influence.
+ */
 const instanceSchema = z
     .string()
     .optional()
-    .describe("Sandbox-only: omit (defaults to sandbox) or pass \"sandbox\".");
+    .describe("OCAPI instance context. Omit or pass \"sandbox\".");
 const createAttributeDefinitionInput = z.object({
     object_type: z.string().describe("System object type, e.g. \"Product\"."),
     attribute_id: z.string().describe("Attribute id (URL id); the body id must match it."),

package/build/sfcc/writes.js

@@ -3,9 +3,10 @@
  * populated by BAPI-584).
  *
  * This is the registration seam that write-surface tickets register through.
- * `register.ts` wires this behind the existing `includeReadTools` SFCC gate, so
- * the write tools become default-on with the reads without touching
- * `register.ts` or `index.ts`.
+ * `register.ts` wires it behind its OWN `includeWriteTools` gate, driven by the
+ * `sfcc-write` profile group (BAPI-817). The nine tools here are destructive, so
+ * they are no longer default-on with the reads: enabling `sfcc` registers the
+ * read profile and nothing from this module.
  *
  * Each write handler follows the foundation recipe:
  *   1. Parse inputs.
@@ -25,7 +26,8 @@ import { registerSitePreferenceWriteTools, SITE_PREFERENCE_WRITE_TOOL_NAMES, } f
  * Write tool names registered by this seam (centralized inventory). Extended by
  * each write-surface ticket — BAPI-583 adds the six system-object write tools,
  * BAPI-584 adds the custom-object attribute-definition and site-preference value
- * write tools.
+ * write tools. These nine have SHIPPED; `registration-inventory.ts` reuses this
+ * array as the `sfcc-write` profile inventory rather than duplicating it.
  */
 export const SFCC_WRITE_TOOL_NAMES = [
     ...SYSTEM_OBJECT_WRITE_TOOL_NAMES,
@@ -47,14 +49,17 @@ export const SFCC_WRITE_TOOL_NAMES = [
  *   4. Call `ocapiPut` or `ocapiPatch` (client.ts) for transport.
  *   5. Route the result through `formatOcapiWriteToolResult` (write-result.ts).
  *
- * Each handler is additionally call-time gated by `withSfccGate` and
- * sandbox-guarded, so registering them here (default-on with the reads) does
- * not weaken the per-call safety model.
+ * Every handler registered here crosses three checks before it can mutate
+ * anything: the resolved-hostname sandbox boundary (registration-level,
+ * `tool-wrapper.ts`), the call-time `withSfccGate` version check, and the
+ * secondary instance-context guard in `write-guard.ts`. Only the first of those
+ * decides which instance is contacted.
  *
  * BAPI-583 registers the system-object write surface here; BAPI-584 adds the
  * custom-object attribute-definition and site-preference value write surfaces
  * alongside it. Later write-surface tickets add their modules the same way,
- * without touching `register.ts`/`index.ts`.
+ * without touching `register.ts`/`index.ts` — a new tool added here is
+ * automatically inside the `sfcc-write` group and inside the target boundary.
  */
 export function registerSfccWriteTools(registerTool, deps) {
     // System-object attribute/group definition writes (BAPI-583).