drupal-mcp-connector 1.5.0 → 1.6.0

package/src/lib/link-checker.js

@@ -0,0 +1,201 @@
+/**
+ * Guarded live link checker — opt-in outbound HTTP for the broken-links audit.
+ *
+ * Single responsibility: given a set of URLs, perform bounded liveness checks
+ * (HEAD, falling back to GET) and report each URL's status. Outbound HTTP is a
+ * privileged capability, so this module is the one place network egress is
+ * allowed during an audit, and only when the caller explicitly opts in.
+ *
+ * Safeguards (see checkLinks):
+ *   - SSRF guard: only http(s); refuse loopback/private/link-local/metadata
+ *     hosts and IP literals in private ranges.
+ *   - Allowlist: external hosts are skipped unless listed in
+ *     `allowedHosts`; same-origin (internal) hosts are always allowed.
+ *   - Caps: bounded concurrency, per-request timeout, and a hard ceiling on the
+ *     number of URLs checked (results flag `truncated` when the ceiling is hit).
+ */
+
+import nodeFetch from "node-fetch";
+
+/** Default per-request timeout (ms). */
+export const DEFAULT_TIMEOUT_MS = 5000;
+/** Default number of concurrent in-flight checks. */
+export const DEFAULT_CONCURRENCY = 5;
+/** Default hard ceiling on URLs checked in one call. */
+export const DEFAULT_MAX_LINKS = 200;
+
+/**
+ * Hostnames that must never be probed regardless of allowlist — loopback and
+ * cloud metadata endpoints.
+ */
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "metadata.google.internal",
+]);
+
+/**
+ * Decide whether a URL is safe to probe: http(s) only, and not pointed at a
+ * loopback, private, link-local, unique-local, or metadata address. Hostnames
+ * that are not IP literals are allowed past the IP-range check (DNS is not
+ * resolved here); the allowlist in checkLinks is the second gate for those.
+ *
+ * @param {string} url Absolute URL to validate.
+ * @returns {{safe: boolean, reason: ?string, host: ?string}} Verdict.
+ */
+export function isSafeUrl(url) {
+  let parsed;
+  try { parsed = new URL(url); }
+  catch { return { safe: false, reason: "unparseable URL", host: null }; }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { safe: false, reason: `unsupported protocol ${parsed.protocol}`, host: parsed.host };
+  }
+
+  // URL.hostname returns IPv6 literals wrapped in brackets; strip them so the
+  // range checks below see a bare address.
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+    return { safe: false, reason: "loopback host", host: parsed.host };
+  }
+  if (isPrivateIp(hostname)) {
+    return { safe: false, reason: "private or link-local address", host: parsed.host };
+  }
+  return { safe: true, reason: null, host: parsed.host };
+}
+
+/**
+ * Whether a hostname is an IP literal in a loopback/private/link-local/ULA range.
+ * Non-IP hostnames return false (resolution happens at fetch time, not here).
+ * @param {string} hostname Lowercased hostname from a URL.
+ * @returns {boolean} True when the literal IP is in a blocked range.
+ */
+function isPrivateIp(hostname) {
+  // IPv6 literals arrive bracket-stripped from URL.hostname.
+  if (hostname.includes(":")) {
+    if (hostname === "::1") return true;                 // loopback
+    if (hostname.startsWith("fe80")) return true;        // link-local
+    if (hostname.startsWith("fc") || hostname.startsWith("fd")) return true; // ULA
+    if (hostname.startsWith("::ffff:")) return isPrivateIp(hostname.slice(7)); // mapped v4
+    return false;
+  }
+  const m = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return false;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  if (a === 127) return true;                            // 127.0.0.0/8 loopback
+  if (a === 10) return true;                             // 10.0.0.0/8
+  if (a === 0) return true;                              // 0.0.0.0/8
+  if (a === 169 && b === 254) return true;               // 169.254.0.0/16 link-local + metadata
+  if (a === 172 && b >= 16 && b <= 31) return true;      // 172.16.0.0/12
+  if (a === 192 && b === 168) return true;               // 192.168.0.0/16
+  return false;
+}
+
+/**
+ * Check a list of URLs for liveness with bounded concurrency.
+ *
+ * @param {string[]} urls URLs to check (duplicates are de-duped).
+ * @param {object} [opts]
+ * @param {string[]} [opts.allowedHosts] Hosts allowed for external probes. A
+ *   same-origin host (see opts.internalHost) is always allowed.
+ * @param {?string} [opts.internalHost] The site's own host; never needs listing.
+ * @param {number} [opts.maxConcurrency] In-flight cap (default 5).
+ * @param {number} [opts.timeoutMs] Per-request timeout (default 5000).
+ * @param {number} [opts.maxLinks] Hard ceiling on URLs checked (default 200).
+ * @param {Function} [opts.fetchImpl] Injected fetch (for tests); defaults to node-fetch.
+ * @returns {Promise<{checked: number, truncated: boolean, results: Array<{
+ *   url: string, ok: boolean, status: ?number, skipped: boolean, reason: ?string}>}>}
+ */
+export async function checkLinks(urls, opts = {}) {
+  const {
+    allowedHosts = [],
+    internalHost = null,
+    maxConcurrency = DEFAULT_CONCURRENCY,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxLinks = DEFAULT_MAX_LINKS,
+    fetchImpl = nodeFetch,
+  } = opts;
+
+  const allow = new Set(allowedHosts.map((h) => String(h).toLowerCase()));
+  if (internalHost) allow.add(String(internalHost).toLowerCase());
+
+  const unique = [...new Set(urls)];
+  const truncated = unique.length > maxLinks;
+  const queue = unique.slice(0, maxLinks);
+
+  const results = [];
+  let cursor = 0;
+  /**
+   * Worker: pull URLs off the shared queue until drained.
+   * @returns {Promise<void>}
+   */
+  async function worker() {
+    while (cursor < queue.length) {
+      const url = queue[cursor++];
+      results.push(await checkOne(url, { allow, timeoutMs, fetchImpl }));
+    }
+  }
+  const workers = Array.from({ length: Math.max(1, Math.min(maxConcurrency, queue.length)) }, worker);
+  await Promise.all(workers);
+
+  return { checked: results.length, truncated, results };
+}
+
+/**
+ * Check a single URL, applying the SSRF guard and host allowlist before any
+ * network call. Safe failures (blocked/not-allowlisted) are returned as
+ * `skipped`, not errors.
+ * @param {string} url URL to check.
+ * @param {{allow: Set<string>, timeoutMs: number, fetchImpl: Function}} ctx Shared context.
+ * @returns {Promise<{url: string, ok: boolean, status: ?number, skipped: boolean, reason: ?string}>}
+ */
+async function checkOne(url, { allow, timeoutMs, fetchImpl }) {
+  const guard = isSafeUrl(url);
+  if (!guard.safe) {
+    return { url, ok: false, status: null, skipped: true, reason: guard.reason };
+  }
+  if (!allow.has(guard.host.toLowerCase())) {
+    return { url, ok: false, status: null, skipped: true, reason: "host not in allowlist" };
+  }
+
+  // HEAD first; some servers reject HEAD (405/501) so retry once with GET.
+  const head = await timedFetch(url, "HEAD", { timeoutMs, fetchImpl });
+  if (head.status && head.status !== 405 && head.status !== 501) {
+    return finalize(url, head);
+  }
+  const get = await timedFetch(url, "GET", { timeoutMs, fetchImpl });
+  return finalize(url, get);
+}
+
+/**
+ * Build the public result record from a fetch outcome. Treats 2xx/3xx as ok.
+ * @param {string} url URL checked.
+ * @param {{status: ?number, error: ?string}} res Fetch outcome.
+ * @returns {{url: string, ok: boolean, status: ?number, skipped: boolean, reason: ?string}}
+ */
+function finalize(url, res) {
+  if (res.error) return { url, ok: false, status: null, skipped: false, reason: res.error };
+  const ok = res.status >= 200 && res.status < 400;
+  return { url, ok, status: res.status, skipped: false, reason: ok ? null : `HTTP ${res.status}` };
+}
+
+/**
+ * Perform a single fetch with an abort-based timeout. Never throws — network and
+ * timeout failures are returned as `{ status: null, error }`.
+ * @param {string} url URL to fetch.
+ * @param {"HEAD"|"GET"} method HTTP method.
+ * @param {{timeoutMs: number, fetchImpl: Function}} ctx Timeout + fetch impl.
+ * @returns {Promise<{status: ?number, error: ?string}>}
+ */
+async function timedFetch(url, method, { timeoutMs, fetchImpl }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { method, redirect: "follow", signal: controller.signal });
+    return { status: res.status, error: null };
+  } catch (err) {
+    const reason = err?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : (err?.message || "request failed");
+    return { status: null, error: reason };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/lib/server-tools.js

@@ -309,6 +309,23 @@ export async function callServerTool(site, toolName, args = {}) {
   }
 }
 
+/**
+ * Extract the structured data a server tool returned, for callers (the audit
+ * tools) that need to inspect the payload rather than relay it. Prefers the MCP
+ * `structuredContent` field; otherwise parses the joined text content as JSON,
+ * falling back to the raw text when it isn't JSON.
+ * @param {object} result MCP tools/call result (as returned by callServerTool).
+ * @returns {*} Parsed structured data, raw text, or null when empty.
+ */
+export function toolResultData(result) {
+  if (!result) return null;
+  if (result.structuredContent !== undefined) return result.structuredContent;
+  const text = extractTextContent(result);
+  if (!text) return null;
+  try { return JSON.parse(text); }
+  catch { return text; }
+}
+
 /**
  * Pull the concatenated text from an MCP tool result's content array.
  * @param {object} result MCP tools/call result.

package/src/tools/audit-composite.js

@@ -0,0 +1,152 @@
+/**
+ * Tool group: Composite site-health audit.
+ *
+ * `drupal_audit_site_health` runs a configurable battery of the individual audit
+ * tools (content + links + config) and rolls their results into one scored
+ * dashboard. Each section runs independently: a section that throws or returns a
+ * gated/unavailable payload is recorded as such and does not abort the others, so
+ * the dashboard is always returned. The roll-up grade reflects only the sections
+ * that produced findings.
+ *
+ * This module composes the other tool groups' handlers rather than re-querying
+ * the backend, so its behavior always matches the standalone tools.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import * as reports from "./reports.js";
+import * as reportsLinks from "./reports-links.js";
+import * as reportsConfig from "./reports-config.js";
+import * as reportsContent from "./reports-content.js";
+
+/**
+ * The audit battery. Each section names its group, the handler to run, the args
+ * to pass (derived from the composite's options), and a scorer that extracts an
+ * `{ issues, high }` signal from the section's result.
+ */
+const SECTIONS = [
+  // Content
+  { key: "content_summary", group: "content", run: (o) => reports.handlers.drupal_report_content_summary({ site: o.site }), score: () => ({ issues: 0, high: 0 }) },
+  { key: "stale_content", group: "content", run: (o) => reports.handlers.drupal_report_stale_content({ site: o.site, type: o.type, days: 180, limit: o.sampleSize }), score: (r) => ({ issues: (r.findings || r.nodes || []).length, high: 0 }) },
+  { key: "seo_audit", group: "content", run: (o) => reports.handlers.drupal_report_seo_audit({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: sumIssueCounts(r.issues), high: 0 }) },
+  { key: "accessibility", group: "content", run: (o) => reports.handlers.drupal_report_accessibility_audit({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: sumIssueCounts(r.issues), high: 0 }) },
+  { key: "duplicate_content", group: "content", run: (o) => reportsContent.handlers.drupal_report_duplicate_content({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: r.duplicateGroups || 0, high: 0 }) },
+  { key: "readability", group: "content", run: (o) => reportsContent.handlers.drupal_report_readability({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: (r.hardToRead || []).length, high: 0 }) },
+  { key: "pii_exposure", group: "content", run: (o) => reportsContent.handlers.drupal_report_pii_exposure({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: r.flaggedNodes || 0, high: r.flaggedNodes || 0 }) },
+  // Links
+  { key: "broken_links", group: "links", run: (o) => reportsLinks.handlers.drupal_report_broken_links({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: r.summary?.malformed || 0, high: 0 }) },
+  { key: "redirect_health", group: "links", run: (o) => reportsLinks.handlers.drupal_report_redirect_health({ site: o.site }), score: (r) => ({ issues: (r.summary?.duplicateSources || 0) + (r.summary?.chains || 0) + (r.summary?.loops || 0), high: r.summary?.loops || 0 }) },
+  { key: "alias_coverage", group: "links", run: (o) => reportsLinks.handlers.drupal_report_alias_coverage({ site: o.site, type: o.type, sampleSize: o.sampleSize }), score: (r) => ({ issues: (r.totalMissingAlias || 0) + (r.aliasConflicts?.conflicting?.length || 0), high: 0 }) },
+  { key: "log_404", group: "links", run: (o) => reportsLinks.handlers.drupal_report_404_log({ site: o.site }), score: (r) => ({ issues: (r.findings || []).length, high: 0 }) },
+  // Config
+  { key: "config_best_practices", group: "config", run: (o) => reportsConfig.handlers.drupal_audit_config_best_practices({ site: o.site }), score: (r) => ({ issues: (r.counts?.high || 0) + (r.counts?.medium || 0) + (r.counts?.low || 0), high: r.counts?.high || 0 }) },
+  { key: "module_audit", group: "config", run: (o) => reportsConfig.handlers.drupal_report_module_audit({ site: o.site }), score: (r) => ({ issues: (r.summary?.devModulesEnabled || 0) + (r.summary?.securityAdvisories || 0), high: r.summary?.securityAdvisories || 0 }) },
+  { key: "permission_audit", group: "config", run: (o) => reportsConfig.handlers.drupal_report_permission_audit({ site: o.site }), score: (r) => ({ issues: (r.findings || []).length, high: r.counts?.high || 0 }) },
+];
+
+const SECTION_KEYS = SECTIONS.map((s) => s.key);
+
+/**
+ * Sum the `count` values out of an seo/accessibility audit's `issues` map.
+ * @param {object} issues The audit's keyed issues object.
+ * @returns {number} Total issue count.
+ */
+function sumIssueCounts(issues) {
+  if (!issues || typeof issues !== "object") return 0;
+  return Object.values(issues).reduce((sum, v) => sum + (v?.count || 0), 0);
+}
+
+/**
+ * Whether a section result is a gated/unavailable payload.
+ * @param {object} r A section result.
+ * @returns {boolean}
+ */
+function isGated(r) {
+  return Boolean(r && (r.unavailable === true || r.gated === true));
+}
+
+/**
+ * Convert aggregate high/issue counts into a letter grade.
+ * @param {number} high Total high-severity findings.
+ * @param {number} issues Total findings.
+ * @returns {"A"|"B"|"C"|"D"|"F"} Roll-up grade.
+ */
+function grade(high, issues) {
+  if (high === 0 && issues === 0) return "A";
+  if (high === 0 && issues <= 5) return "B";
+  if (high <= 2) return "C";
+  if (high <= 5) return "D";
+  return "F";
+}
+
+/**
+ * Run a battery of audits and roll the results into a scored dashboard.
+ *
+ * @param {object} args - { site?, type?, sampleSize?, sections? }.
+ * @returns {Promise<object>} The dashboard: per-section status + a roll-up grade.
+ */
+async function siteHealth({ site: siteName, type = "article", sampleSize = 50, sections }) {
+  const site = getSiteConfig(siteName);
+  const selected = sections && sections.length
+    ? SECTIONS.filter((s) => sections.includes(s.key))
+    : SECTIONS;
+  const opts = { site: site._name, type, sampleSize };
+
+  const results = [];
+  let totalHigh = 0;
+  let totalIssues = 0;
+  for (const section of selected) {
+    try {
+      const result = await section.run(opts);
+      if (isGated(result)) {
+        results.push({ key: section.key, group: section.group, status: "unavailable", reason: result.reason || result.attempts?.join("; ") || null });
+        continue;
+      }
+      const { issues, high } = section.score(result);
+      totalHigh += high;
+      totalIssues += issues;
+      results.push({ key: section.key, group: section.group, status: "ok", issues, high, result });
+    } catch (err) {
+      results.push({ key: section.key, group: section.group, status: "error", error: err?.message || String(err) });
+    }
+  }
+
+  const byStatus = (s) => results.filter((r) => r.status === s).length;
+  return {
+    site: site._name,
+    type,
+    grade: grade(totalHigh, totalIssues),
+    summary: {
+      sectionsRun: results.length,
+      ok: byStatus("ok"),
+      unavailable: byStatus("unavailable"),
+      errored: byStatus("error"),
+      totalHigh,
+      totalIssues,
+    },
+    sections: results,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions & handlers
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_audit_site_health",
+    description: "Composite site-health dashboard: runs a battery of content, link, and configuration audits and rolls them into one scored report with a letter grade. Each section degrades independently — gated/errored sections are recorded, not fatal. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        site:       { type: "string" },
+        type:       { type: "string", description: "Primary content type for content/link sections (default: article)" },
+        sampleSize: { type: "number", default: 50, description: "Per-section scan cap (kept small for a fast roll-up)" },
+        sections:   { type: "array", items: { type: "string", enum: SECTION_KEYS }, description: `Subset of sections to run (default: all). Available: ${SECTION_KEYS.join(", ")}` },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_audit_site_health: siteHealth,
+};

package/src/tools/drush.js

@@ -93,8 +93,12 @@ function resolveKeyPath(rawPath) {
  *
  * Security: args are individually shell-escaped via sanitizeSshArg().
  * No raw user input is ever interpolated directly into the command string.
+ *
+ * Exported so the audit tool groups can reuse the hardened bridge for their
+ * drush fallback paths (e.g. config:status, pm:list, watchdog:show) without
+ * re-implementing SSH handling.
  */
-function sshDrush(site, drushArgs, timeoutMs = 30000) {
+export function sshDrush(site, drushArgs, timeoutMs = 30000) {
   const sshCfg  = getDrushConfig(site);
   assertCommandAllowed(sshCfg, drushArgs[0]);
   const keyPath = resolveKeyPath(sshCfg.keyPath);
@@ -110,7 +114,7 @@ function sshDrush(site, drushArgs, timeoutMs = 30000) {
   const drushBin    = `${drupalRoot}/vendor/bin/drush`;
   const command     = `cd ${sanitizeSshArg(drupalRoot)} && ${drushBin} ${escapedArgs} --yes`;
 
-  console.error(`[drush-bridge] ${site._name}: drush ${drushArgs.join(" ")}`);
+  console.error(`[drush-bridge] ${site._name}: drush ${redactSecretArgs(drushArgs)}`);
 
   return new Promise((resolve, reject) => {
     const conn  = new Client();
@@ -165,10 +169,28 @@ function sshDrush(site, drushArgs, timeoutMs = 30000) {
   });
 }
 
+/**
+ * Redact secret-bearing flag values from a Drush argument list for safe logging.
+ * `user:create` passes `--password=…`, and other admin flows may pass tokens/keys;
+ * the operational log must not echo them in clear text.
+ * @param {string[]} drushArgs The Drush subcommand + flags.
+ * @returns {string} A space-joined, secret-redacted rendering for the log line.
+ */
+export function redactSecretArgs(drushArgs) {
+  const SECRET_FLAG = /^(--(?:password|pass|token|secret|client[-_]?secret|api[-_]?key|key)=)(.*)$/i;
+  return drushArgs
+    .map((arg) => {
+      const m = String(arg).match(SECRET_FLAG);
+      return m ? `${m[1]}***` : arg;
+    })
+    .join(" ");
+}
+
 /**
  * Parse Drush JSON output; fall back to raw string if not JSON.
+ * Exported for reuse by the audit tool groups' drush fallback paths.
  */
-function parseDrush(raw) {
+export function parseDrush(raw) {
   if (!raw) return null;
   try   { return JSON.parse(raw); }
   catch { return raw; }

package/src/tools/nodes.js

@@ -9,7 +9,118 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { resolveSecurityConfig, redactCanonicalEntity } from "../lib/security.js";
+import { resolveSecurityConfig, redactCanonicalEntity, assertWriteAllowed } from "../lib/security.js";
+import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
+
+/** Fallback language for an alias when the node exposes none. */
+const DEFAULT_ALIAS_LANGCODE = "en";
+
+/**
+ * Normalize a URL-alias path for storage/comparison: trim, ensure a single
+ * leading slash, drop a trailing slash (except root).
+ * @param {*} value A raw alias.
+ * @returns {?string} The normalized alias, or null when empty.
+ */
+function normalizeAlias(value) {
+  if (value === undefined || value === null) return null;
+  let s = String(value).trim();
+  if (!s) return null;
+  if (!s.startsWith("/")) s = `/${s}`;
+  if (s.length > 1) s = s.replace(/\/+$/, "");
+  return s;
+}
+
+/**
+ * Resolve the `path` attribute to send on an alias-aware node write so the alias
+ * actually persists, and decide whether a rename redirect is needed.
+ *
+ * The bug (DEV-116): JSON:API deserializes `{ alias, pathauto }` onto the node's
+ * `path` field, dropping the existing alias's `pid`; Drupal's `PathItem::postSave`
+ * then *creates a duplicate* `path_alias` (the older one stays canonical) instead
+ * of updating in place. The fix is to round-trip the existing `pid` so the update
+ * is in place. DEV-114's path-omitted "preserve" had the same defect (no `pid`),
+ * so it is fixed here too.
+ *
+ * @param {object} args - { backend, type, id, providedPath, isCreate }.
+ * @returns {Promise<{pathAttr: (object|undefined), redirect: ?object}>}
+ *   `pathAttr` is the `path` value to send (or undefined to omit, letting pathauto
+ *   run on create); `redirect` is `{ from, to, nid }` when a rename redirect is due.
+ */
+async function resolvePathWrite({ backend, type, id, providedPath, isCreate }) {
+  const info = id
+    ? await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}))
+    : {};
+  const oldAlias = normalizeAlias(info.alias);
+  const langcode = info.langcode || DEFAULT_ALIAS_LANGCODE;
+
+  if (providedPath && typeof providedPath === "object") {
+    // Explicit alias set/replace → manual alias, round-trip the existing pid so
+    // Drupal updates in place rather than creating a duplicate.
+    if (providedPath.alias) {
+      const newAlias = normalizeAlias(providedPath.alias);
+      const pathAttr = { alias: newAlias, pathauto: false, langcode };
+      if (info.pid !== undefined && info.pid !== null) pathAttr.pid = info.pid;
+      const redirect = !isCreate && oldAlias && oldAlias !== newAlias
+        ? { from: oldAlias, to: newAlias, nid: info.drupalId }
+        : null;
+      return { pathAttr, redirect };
+    }
+    // Caller passed `path` without an alias (e.g. re-enabling pathauto) — respect it as-is.
+    return { pathAttr: providedPath, redirect: null };
+  }
+
+  // No explicit path on update → preserve the current alias *with its pid* so the
+  // save can neither revert nor duplicate it.
+  if (!isCreate && oldAlias) {
+    const pathAttr = { alias: oldAlias, pathauto: false, langcode };
+    if (info.pid !== undefined && info.pid !== null) pathAttr.pid = info.pid;
+    return { pathAttr, redirect: null };
+  }
+
+  // Create without an explicit path → omit it so pathauto generates the alias.
+  return { pathAttr: undefined, redirect: null };
+}
+
+/**
+ * Best-effort create a 301 redirect from a node's old alias to the node after a
+ * rename, so the previous URL keeps resolving. Governed like any redirect write;
+ * never fails the node update (failures are reported, not thrown). Idempotent:
+ * skips when a redirect already exists for the source.
+ *
+ * @param {object} backend Resolved backend.
+ * @param {object} sec Resolved security config.
+ * @param {{from: string, to: string, nid: ?(number|string)}} redirect
+ * @returns {Promise<object>} Outcome `{ created, ... }` for the response.
+ */
+async function createRenameRedirect(backend, sec, redirect) {
+  try {
+    assertWriteAllowed(sec, "create", REDIRECT_ENTITY_TYPE, REDIRECT_ENTITY_TYPE);
+  } catch {
+    return { created: false, reason: "redirect creation not permitted by policy", source: redirect.from };
+  }
+  // Prefer an alias-independent target so a future rename can't break the redirect.
+  const target = redirect.nid !== undefined && redirect.nid !== null
+    ? `entity:node/${redirect.nid}`
+    : redirect.to;
+  const sourceStored = redirect.from.replace(/^\/+/, "");
+  try {
+    const existing = await backend.listEntities({
+      entityType: REDIRECT_ENTITY_TYPE, bundle: REDIRECT_ENTITY_TYPE,
+      filters: [{ field: "redirect_source.path", op: "eq", value: sourceStored }],
+      page: { limit: 1 },
+    }).catch(() => null);
+    if (existing?.entities?.length) {
+      return { created: false, reason: "redirect already exists", source: redirect.from };
+    }
+    await backend.createEntity({
+      entityType: REDIRECT_ENTITY_TYPE, bundle: REDIRECT_ENTITY_TYPE,
+      attributes: buildRedirectAttributes(redirect.from, target, 301),
+    });
+    return { created: true, source: redirect.from, target };
+  } catch (err) {
+    return { created: false, reason: err?.message || String(err), source: redirect.from };
+  }
+}
 
 /**
  * Build a Drupal body field descriptor from plain HTML + optional summary.
@@ -119,7 +230,16 @@ async function createNode({ site: siteName, type, title, body, summary, status,
   if (bodyAttr) attributes.body = bodyAttr;
   if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes };
   const backend = await resolveBackend(site);
-  return backend.createEntity({ entityType: "node", bundle: type, attributes });
+  // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
+  // `path` is omitted so pathauto generates the alias (DEV-116).
+  const { pathAttr } = await resolvePathWrite({ backend, type, id: null, providedPath: attributes.path, isCreate: true });
+  if (pathAttr === undefined) delete attributes.path;
+  else attributes.path = pathAttr;
+  const created = await backend.createEntity({ entityType: "node", bundle: type, attributes });
+  // Honest response: re-read so the persisted alias (explicit or pathauto-generated)
+  // is reflected rather than the pre-alias write response.
+  const fresh = await backend.getEntity({ entityType: "node", bundle: type, id: created.id }).catch(() => null);
+  return fresh ?? created;
 }
 
 /**
@@ -149,13 +269,21 @@ async function updateNode({ site: siteName, type, id, title, body, summary, stat
   if (bodyAttr) attributes.body = bodyAttr;
   if (dryRun) return { dryRun: true, operation: "update", entityType: "node", bundle: type, id, attributes };
   const backend = await resolveBackend(site);
-  // Preserve the existing URL alias when the caller didn't set `path`: read the
-  // current alias and re-pin it (pathauto off) so the save can't revert it.
-  if (attributes.path === undefined) {
-    const current = await backend.getEntity({ entityType: "node", bundle: type, id });
-    if (current?.url) attributes.path = { alias: current.url, pathauto: 0 };
-  }
-  return backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
+  const sec = resolveSecurityConfig(site);
+  // Alias handling (DEV-116): an explicit `path.alias` is set in place by
+  // round-tripping the existing alias's pid (no duplicate); a path-less update
+  // re-pins the current alias *with its pid* so the save can't revert/duplicate
+  // it. A rename (alias changed) also gets a 301 redirect from the old path.
+  const { pathAttr, redirect } = await resolvePathWrite({ backend, type, id, providedPath: attributes.path, isCreate: false });
+  if (pathAttr === undefined) delete attributes.path;
+  else attributes.path = pathAttr;
+  await backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
+  const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
+  // Honest response: re-read persisted state so the returned `url` is the alias
+  // that actually resolves, never the just-sent value.
+  const fresh = await backend.getEntity({ entityType: "node", bundle: type, id }).catch(() => null);
+  if (fresh && redirectResult) return { ...fresh, _redirect: redirectResult };
+  return fresh ?? { id };
 }
 
 /**

package/src/tools/redirects.js

@@ -83,6 +83,32 @@ function assertStatusCode(code) {
   return code;
 }
 
+/** Entity type id for redirects, exported so side-effect callers can reuse it. */
+export const REDIRECT_ENTITY_TYPE = REDIRECT_TYPE;
+
+/**
+ * Build the JSON:API attribute map for a `redirect` entity from a plain
+ * source/target, applying the leading-slash and link-URI normalization that
+ * keeps a created redirect live. Exported so other tools (e.g. the node
+ * rename-redirect side-effect in nodes.js) create redirects identically.
+ *
+ * @param {string} source Old path (leading slash optional; stripped).
+ * @param {string} target Destination path / `entity:node/ID` / absolute URL.
+ * @param {number} [statusCode] HTTP redirect code (default 301).
+ * @param {string} [language] Redirect language (default 'und').
+ * @returns {object} The redirect attribute map for backend.createEntity.
+ * @throws {Error} If the status code is unsupported.
+ */
+export function buildRedirectAttributes(source, target, statusCode = 301, language = "und") {
+  assertStatusCode(statusCode);
+  return {
+    redirect_source: { path: normalizeSource(source), query: null },
+    redirect_redirect: { uri: normalizeTargetUri(target) },
+    status_code: statusCode,
+    language,
+  };
+}
+
 /**
  * Create an active URL redirect.
  *
@@ -98,18 +124,14 @@ function assertStatusCode(code) {
 async function createRedirect({ site: siteName, source, target, statusCode = 301, language = "und" }) {
   if (!source) throw new Error("A redirect 'source' path is required (e.g. '/old-path').");
   if (!target) throw new Error("A redirect 'target' is required (a path, 'entity:node/ID', or an absolute URL).");
-  assertStatusCode(statusCode);
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", REDIRECT_TYPE, REDIRECT_TYPE);
   const backend = await resolveBackend(site);
-  const attributes = {
-    redirect_source: { path: normalizeSource(source), query: null },
-    redirect_redirect: { uri: normalizeTargetUri(target) },
-    status_code: statusCode,
-    language,
-  };
-  return backend.createEntity({ entityType: REDIRECT_TYPE, bundle: REDIRECT_TYPE, attributes });
+  return backend.createEntity({
+    entityType: REDIRECT_TYPE, bundle: REDIRECT_TYPE,
+    attributes: buildRedirectAttributes(source, target, statusCode, language),
+  });
 }
 
 /**