drupal-mcp-connector 2.7.4 → 2.9.0

package/src/lib/contracts/evidence-sink.js

@@ -0,0 +1,67 @@
+/**
+ * Evidence-sink contract (#181).
+ *
+ * When policy or assurance class requires durable evidence, failure to write
+ * it fails the governed action. Advisory writes may degrade.
+ */
+
+import { ContractError, REASON } from "./decisions.js";
+
+/**
+ * @typedef {Object} EvidenceSink
+ * @property {(receipt: object) => void} writeRequired
+ * @property {(receipt: object) => {ok: boolean, degraded?: boolean}} writeAdvisory
+ */
+
+/**
+ * In-process evidence sink. `failRequired` makes every required write fail.
+ * `failFinalRequired` fails only the post-mutation receipt (outcome other
+ * than `pending`).
+ *
+ * @param {{failRequired?: boolean, failFinalRequired?: boolean}} [options]
+ * @returns {EvidenceSink & {records: object[]}}
+ */
+export function createMemoryEvidenceSink({
+  failRequired = false,
+  failFinalRequired = false,
+} = {}) {
+  const records = [];
+
+  return Object.freeze({
+    records,
+    /**
+     * @param {object} receipt
+     * @returns {void}
+     */
+    writeRequired(receipt) {
+      if (failRequired || (failFinalRequired && receipt?.outcome !== "pending")) {
+        throw new ContractError(
+          "Required evidence write failed.",
+          REASON.EVIDENCE_WRITE_FAILED,
+        );
+      }
+      records.push({ required: true, receipt });
+    },
+
+    /**
+     * @param {object} receipt
+     * @returns {{ok: boolean}}
+     */
+    writeAdvisory(receipt) {
+      records.push({ required: false, receipt });
+      return { ok: true };
+    },
+  });
+}
+
+/**
+ * Whether this action class must persist evidence at the given assurance.
+ *
+ * @param {string} actionClass
+ * @param {string} assuranceClass
+ * @returns {boolean}
+ */
+export function requiresEvidence(actionClass, assuranceClass) {
+  if (assuranceClass === "advisory") return false;
+  return actionClass === "publish_or_destructive" || actionClass === "control_plane";
+}

package/src/lib/contracts/fixtures.js

@@ -0,0 +1,117 @@
+/**
+ * In-process contract fixtures (#181).
+ *
+ * These implement relay / approval / evidence-sink / backend roles for the
+ * Drupal conformance kit. They are not a second system-of-record adapter.
+ */
+
+import { randomUUID } from "node:crypto";
+import { createMemoryApproval } from "./approval.js";
+import { createMemoryEvidenceSink } from "./evidence-sink.js";
+import { createLocalRelay } from "./relay.js";
+
+export { createMemoryApproval, createMemoryEvidenceSink, createLocalRelay };
+
+/**
+ * In-memory backend used by the Drupal adapter during conformance.
+ *
+ * @param {object} [options]
+ * @param {object[]} [options.entities]
+ * @param {object} [options.mismatch] Forced observed fields after write.
+ * @returns {object}
+ */
+export function createMemoryBackend({ entities = [], mismatch } = {}) {
+  const store = new Map();
+  for (const entity of entities) {
+    store.set(entity.id, { ...entity });
+  }
+
+  return Object.freeze({
+    store,
+    /**
+     * @param {{id: string}} ref
+     * @returns {Promise<object|null>}
+     */
+    async getEntity(ref) {
+      return store.get(ref.id) ?? null;
+    },
+
+    /**
+     * @param {object} input
+     * @returns {Promise<object>}
+     */
+    async createEntity(input) {
+      const id = input.id || randomUUID();
+      const attributes = { ...(input.attributes ?? {}) };
+      const entity = applyMismatch({
+        id,
+        entityType: input.entityType,
+        bundle: input.bundle,
+        status: attributes.status,
+        attributes,
+      }, mismatch);
+      store.set(id, entity);
+      return entity;
+    },
+
+    /**
+     * @param {object} input
+     * @returns {Promise<object>}
+     */
+    async updateEntity(input) {
+      const prev = store.get(input.id) ?? { id: input.id };
+      const attributes = { ...(prev.attributes ?? {}), ...(input.attributes ?? {}) };
+      const entity = applyMismatch({
+        ...prev,
+        entityType: input.entityType ?? prev.entityType,
+        bundle: input.bundle ?? prev.bundle,
+        status: attributes.status ?? prev.status,
+        attributes,
+      }, mismatch);
+      store.set(input.id, entity);
+      return entity;
+    },
+
+    /**
+     * @param {{id: string}} ref
+     * @returns {Promise<void>}
+     */
+    async deleteEntity(ref) {
+      store.delete(ref.id);
+    },
+
+    /**
+     * @returns {Promise<Map<string, object>>}
+     */
+    async captureState() {
+      return new Map(
+        [...store.entries()].map(([id, entity]) => [id, structuredClone(entity)]),
+      );
+    },
+
+    /**
+     * @param {Map<string, object>} snapshot
+     * @returns {Promise<void>}
+     */
+    async restoreState(snapshot) {
+      store.clear();
+      for (const [id, entity] of snapshot) {
+        store.set(id, structuredClone(entity));
+      }
+    },
+  });
+}
+
+/**
+ * @param {object} entity
+ * @param {object|undefined} mismatch
+ * @returns {object}
+ */
+function applyMismatch(entity, mismatch) {
+  if (!mismatch) return entity;
+  const next = { ...entity, ...mismatch };
+  if (mismatch.status !== undefined) {
+    next.attributes = { ...(entity.attributes ?? {}), status: mismatch.status };
+  }
+  return next;
+}

package/src/lib/contracts/index.js

@@ -0,0 +1,46 @@
+/**
+ * Public adapter-contract surface (#181).
+ *
+ * Provider-neutral evaluator, relay, approval, evidence-sink, and
+ * system-of-record contracts, plus the Drupal reference adapter. Model and
+ * agent vendors are not part of this module.
+ */
+
+export {
+  ADAPTER_CONTRACT_POLICY_REVISION,
+  ADAPTER_CONTRACT_VERSION,
+  negotiateContractVersion,
+} from "./version.js";
+
+export {
+  ACTION_CLASSES,
+  ASSURANCE_CLASSES,
+  DECISION_RESULTS,
+  assertActionClass,
+  assertAssuranceClass,
+  assertDecisionResult,
+  createActionManifest,
+  createDecisionRecord,
+  createExecutionReceipt,
+  createIdentityContext,
+  createObligation,
+  digestPayload,
+  stableStringify,
+} from "./types.js";
+
+export {
+  ContractError,
+  REASON,
+  VENDOR_FIELD_NAMES,
+  assertNoVendorFields,
+  composeDecisions,
+  unionObligations,
+} from "./decisions.js";
+
+export { createEvaluator } from "./evaluator.js";
+export { createLocalRelay, hintTargetName } from "./relay.js";
+export { createMemoryApproval } from "./approval.js";
+export { createMemoryEvidenceSink, requiresEvidence } from "./evidence-sink.js";
+export { bindApprovalForExecute, comparePostconditions } from "./system-of-record.js";
+export { createMemoryBackend } from "./fixtures.js";
+export { createDrupalAdapter, mapDrupalAction } from "./drupal.js";

package/src/lib/contracts/relay.js

@@ -0,0 +1,83 @@
+/**
+ * Tenant-relay contract (#181).
+ *
+ * Resolves the authoritative target for a principal. Caller-supplied site,
+ * tenant, environment, or target fields are hints. They never become
+ * authority. Vendor tunnel implementations stay outside this contract.
+ */
+
+import { resolveAuthoritativeTarget } from "../principal.js";
+import { ContractError, REASON } from "./decisions.js";
+
+/**
+ * @typedef {Object} TenantRelay
+ * @property {(identity: object|null, hints?: object) => {site: object, source: string, name: string}} resolve
+ */
+
+/**
+ * Local, vendor-neutral relay over configured sites.
+ *
+ * @param {object} params
+ * @param {Array<object>} params.sites
+ * @param {object|null} [params.grants]
+ * @param {string} [params.defaultSite]
+ * @returns {TenantRelay}
+ */
+export function createLocalRelay({ sites, grants = null, defaultSite } = {}) {
+  const catalog = Array.isArray(sites) ? sites : [];
+
+  return Object.freeze({
+    /**
+     * @param {object|null} identity
+     * @param {object} [hints]
+     * @returns {{site: object, source: string, name: string}}
+     */
+    resolve(identity, hints = {}) {
+      if (!identity) {
+        const hintName = hintTargetName(hints);
+        if (hintName) {
+          const site = catalog.find((entry) => entry._name === hintName);
+          if (!site) {
+            throw new ContractError(
+              "Caller hint is not an authoritative target.",
+              REASON.TENANT_ESCAPE,
+            );
+          }
+          return { site, source: "hint", name: site._name };
+        }
+        const fallback = catalog.find((entry) => entry._name === defaultSite) || catalog[0];
+        if (!fallback) {
+          throw new ContractError("No target configured.", REASON.TENANT_ESCAPE);
+        }
+        return { site: fallback, source: "default", name: fallback._name };
+      }
+
+      try {
+        return resolveAuthoritativeTarget(hints, identity, catalog, {
+          grants,
+          defaultSite,
+        });
+      } catch (err) {
+        throw new ContractError(
+          err instanceof Error ? err.message : "Tenant escape.",
+          REASON.TENANT_ESCAPE,
+        );
+      }
+    },
+  });
+}
+
+/**
+ * First caller hint that can name a target. Order matches
+ * `resolveAuthoritativeTarget`: site, then target, environment, tenant.
+ *
+ * @param {object} [hints]
+ * @returns {string|undefined}
+ */
+export function hintTargetName(hints) {
+  for (const key of ["site", "target", "environment", "tenant"]) {
+    const value = new Map(Object.entries(hints ?? {})).get(key);
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return undefined;
+}

package/src/lib/contracts/system-of-record.js

@@ -0,0 +1,61 @@
+/**
+ * System-of-record adapter contract (#181).
+ *
+ * One adapter maps native operations onto portable action classes, proposes
+ * an immutable manifest, evaluates it, and executes only after the typed
+ * decision (and any required approval) allows it. A second adapter is out
+ * of scope for this package.
+ */
+
+import { ContractError, REASON } from "./decisions.js";
+
+/**
+ * @typedef {Object} SystemOfRecordAdapter
+ * @property {(proposal: object) => string} mapAction
+ * @property {(proposal: object) => object} propose
+ * @property {(manifest: object) => object} evaluate
+ * @property {(manifest: object, decision: object, options?: object) => Promise<object>} execute
+ */
+
+/**
+ * Consume a one-use approval when the decision requires it.
+ *
+ * @param {object} decision
+ * @param {object} manifest
+ * @param {{consume: Function}} [approval]
+ * @param {string} [approvalId]
+ * @param {string} [actor]
+ * @returns {{blocked: boolean}}
+ * @throws {ContractError}
+ */
+export function bindApprovalForExecute(decision, manifest, approval, approvalId, actor) {
+  if (decision.result === "deny") return { blocked: true };
+  if (decision.result !== "require_approval") return { blocked: false };
+  if (!approval) {
+    throw new ContractError("Approval required.", REASON.APPROVAL_REQUIRED);
+  }
+  approval.consume(approvalId, manifest.digest, actor);
+  return { blocked: false };
+}
+
+/**
+ * Compare declared effects with observed target state.
+ *
+ * @param {object|undefined} declared
+ * @param {object|null|undefined} observed
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function comparePostconditions(declared, observed) {
+  if (!declared || typeof declared !== "object") return { ok: true };
+  if (!observed || typeof observed !== "object") {
+    return { ok: false, reason: REASON.POSTCONDITION };
+  }
+  const declaredMap = new Map(Object.entries(declared));
+  const observedMap = new Map(Object.entries(observed));
+  for (const [key, expected] of declaredMap.entries()) {
+    if (observedMap.get(key) !== expected) {
+      return { ok: false, reason: REASON.POSTCONDITION };
+    }
+  }
+  return { ok: true };
+}

package/src/lib/contracts/types.js

@@ -0,0 +1,242 @@
+/**
+ * Typed records at adapter-contract boundaries (#181).
+ *
+ * Identity, decision, and receipt are independently owned. They share ids
+ * but an upstream identity or allow cannot become authority mid-flight.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { ADAPTER_CONTRACT_VERSION } from "./version.js";
+import { assertNoVendorFields } from "./decisions.js";
+
+/** Portable action classes every system-of-record adapter must map onto. */
+export const ACTION_CLASSES = Object.freeze([
+  "bounded_read",
+  "exfiltration_read",
+  "reversible_write",
+  "publish_or_destructive",
+  "control_plane",
+]);
+
+const ACTION_CLASS_SET = new Set(ACTION_CLASSES);
+
+/** Typed decision results. */
+export const DECISION_RESULTS = Object.freeze([
+  "deny",
+  "allow",
+  "allow_with_obligations",
+  "require_approval",
+]);
+
+const DECISION_RESULT_SET = new Set(DECISION_RESULTS);
+
+/** Assurance classes. Never presented as equivalent. */
+export const ASSURANCE_CLASSES = Object.freeze([
+  "source_enforced",
+  "boundary_enforced",
+  "advisory",
+]);
+
+const ASSURANCE_CLASS_SET = new Set(ASSURANCE_CLASSES);
+
+const ACTION_CLASS_MAP = new Map(ACTION_CLASSES.map((name) => [name, name]));
+const DECISION_RESULT_MAP = new Map(DECISION_RESULTS.map((name) => [name, name]));
+const ASSURANCE_CLASS_MAP = new Map(ASSURANCE_CLASSES.map((name) => [name, name]));
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function assertActionClass(value) {
+  if (!ACTION_CLASS_SET.has(value)) {
+    throw new TypeError(`Unknown action class: ${String(value)}`);
+  }
+  return ACTION_CLASS_MAP.get(value);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function assertDecisionResult(value) {
+  if (!DECISION_RESULT_SET.has(value)) {
+    throw new TypeError(`Unknown decision result: ${String(value)}`);
+  }
+  return DECISION_RESULT_MAP.get(value);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function assertAssuranceClass(value) {
+  if (!ASSURANCE_CLASS_SET.has(value)) {
+    throw new TypeError(`Unknown assurance class: ${String(value)}`);
+  }
+  return ASSURANCE_CLASS_MAP.get(value);
+}
+
+/**
+ * Canonical JSON for digesting a manifest. Key order is sorted.
+ * @param {*} value
+ * @returns {string}
+ */
+export function stableStringify(value) {
+  if (value === undefined) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const body = keys
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(new Map(Object.entries(value)).get(key))}`)
+    .join(",");
+  return `{${body}}`;
+}
+
+/**
+ * @param {object} payload
+ * @returns {string}
+ */
+export function digestPayload(payload) {
+  return createHash("sha256").update(stableStringify(payload)).digest("hex");
+}
+
+/**
+ * @param {object} [raw]
+ * @returns {object}
+ */
+export function createIdentityContext(raw = {}) {
+  assertNoVendorFields(raw);
+  const scopes = Array.isArray(raw.scopes) ? raw.scopes.map(String) : [];
+  return Object.freeze({
+    issuer: typeof raw.issuer === "string" ? raw.issuer : "local",
+    subject: typeof raw.subject === "string"
+      ? raw.subject
+      : (typeof raw.sub === "string" ? raw.sub : "local-operator"),
+    clientId: typeof raw.clientId === "string" ? raw.clientId : "local-operator",
+    tenant: typeof raw.tenant === "string" ? raw.tenant : undefined,
+    audience: typeof raw.audience === "string" ? raw.audience : undefined,
+    scopes: Object.freeze(scopes),
+    authTime: raw.authTime,
+    tokenId: typeof raw.tokenId === "string" ? raw.tokenId : undefined,
+    environment: typeof raw.environment === "string" ? raw.environment : undefined,
+  });
+}
+
+/**
+ * @param {{type: string, value?: string}} raw
+ * @returns {{type: string, value?: string}}
+ */
+export function createObligation(raw) {
+  if (!raw || typeof raw.type !== "string" || !raw.type.trim()) {
+    throw new TypeError("Obligation requires a type");
+  }
+  return Object.freeze({ type: raw.type, value: raw.value });
+}
+
+/**
+ * @param {object} raw
+ * @returns {object}
+ */
+export function createDecisionRecord(raw) {
+  assertNoVendorFields(raw);
+  const result = assertDecisionResult(raw.result);
+  const obligations = Array.isArray(raw.obligations)
+    ? raw.obligations.map((item) => createObligation(item))
+    : [];
+  return Object.freeze({
+    decisionId: raw.decisionId || randomUUID(),
+    result,
+    reason: raw.reason,
+    reasons: Object.freeze(Array.isArray(raw.reasons) ? raw.reasons : (raw.reason ? [raw.reason] : [])),
+    obligations: Object.freeze(obligations),
+    actionDigest: raw.actionDigest,
+    target: raw.target ? Object.freeze({ name: raw.target.name }) : undefined,
+    actionClass: raw.actionClass ? assertActionClass(raw.actionClass) : undefined,
+    policyDigest: raw.policyDigest,
+    policyRevision: raw.policyRevision,
+    evaluatorVersion: raw.evaluatorVersion || ADAPTER_CONTRACT_VERSION,
+    expiresAt: raw.expiresAt,
+    challenge: raw.challenge ? Object.freeze({ ...raw.challenge }) : undefined,
+  });
+}
+
+/**
+ * Build an immutable action manifest. The digest is always computed from
+ * the canonical payload — a caller-supplied digest is ignored.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function createActionManifest(raw) {
+  assertNoVendorFields(raw);
+  const actionClass = assertActionClass(raw.actionClass);
+  const attributes = raw.attributes && typeof raw.attributes === "object"
+    ? { ...raw.attributes }
+    : {};
+  assertNoVendorFields(attributes);
+  const expectedEffects = raw.expectedEffects && typeof raw.expectedEffects === "object"
+    ? { ...raw.expectedEffects }
+    : undefined;
+  const target = raw.target && typeof raw.target === "object"
+    ? Object.freeze({ name: raw.target.name, version: raw.target.version })
+    : undefined;
+  if (raw.hints) assertNoVendorFields(raw.hints);
+  const digest = digestPayload({
+    actionClass,
+    operation: raw.operation,
+    entityType: raw.entityType,
+    bundle: raw.bundle,
+    id: raw.id,
+    attributes,
+    expectedEffects,
+    target,
+    tenant: raw.tenant,
+  });
+  return Object.freeze({
+    manifestId: raw.manifestId || randomUUID(),
+    digest,
+    contractVersion: raw.contractVersion || ADAPTER_CONTRACT_VERSION,
+    actionClass,
+    operation: raw.operation,
+    entityType: raw.entityType,
+    bundle: raw.bundle,
+    id: raw.id,
+    attributes: Object.freeze(attributes),
+    expectedEffects: expectedEffects ? Object.freeze(expectedEffects) : undefined,
+    target,
+    tenant: raw.tenant,
+    environment: raw.environment,
+    expiry: raw.expiry,
+    idempotencyKey: raw.idempotencyKey,
+    hints: raw.hints ? Object.freeze({ ...raw.hints }) : undefined,
+    filePath: raw.filePath,
+    html: raw.html,
+  });
+}
+
+/**
+ * @param {object} raw
+ * @returns {object}
+ */
+export function createExecutionReceipt(raw) {
+  assertNoVendorFields(raw);
+  const outcomes = new Set(["ok", "denied", "failed", "unknown", "pending"]);
+  if (!outcomes.has(raw.outcome)) {
+    throw new TypeError(`Unknown receipt outcome: ${String(raw.outcome)}`);
+  }
+  return Object.freeze({
+    receiptId: raw.receiptId || randomUUID(),
+    decisionId: raw.decisionId,
+    outcome: raw.outcome,
+    reason: raw.reason,
+    nativeActor: raw.nativeActor,
+    revisionId: raw.revisionId,
+    before: raw.before,
+    after: raw.after,
+    declaredEffects: raw.declaredEffects,
+    observed: raw.observed,
+    occurredAt: raw.occurredAt || new Date().toISOString(),
+  });
+}

package/src/lib/contracts/version.js

@@ -0,0 +1,52 @@
+/**
+ * Adapter-contract version and negotiation (#181).
+ *
+ * The family of evaluator / relay / approval / evidence-sink / system-of-record
+ * contracts is versioned independently of the npm package and of the
+ * connector↔Sentinel integration contract. Same major is compatible; a
+ * different major is a hard miss.
+ */
+
+import { ContractError, REASON } from "./decisions.js";
+
+/** Published adapter-contract version. */
+export const ADAPTER_CONTRACT_VERSION = "1.0";
+
+/** Policy revision label minted by this connector's local evaluator. */
+export const ADAPTER_CONTRACT_POLICY_REVISION = "connector-local";
+
+/**
+ * @param {string|undefined|null} requested Requested contract version.
+ * @returns {string} The version this process will speak.
+ * @throws {ContractError} when the requested major is not this major.
+ */
+export function negotiateContractVersion(requested) {
+  if (requested === undefined || requested === null || requested === "") {
+    return ADAPTER_CONTRACT_VERSION;
+  }
+  if (typeof requested !== "string" || !isVersionString(requested)) {
+    throw new ContractError(
+      `Unsupported contract version request: ${String(requested)}`,
+      REASON.INCOMPATIBLE_CONTRACT,
+    );
+  }
+  const requestedMajor = requested.split(".")[0];
+  const supportedMajor = ADAPTER_CONTRACT_VERSION.split(".")[0];
+  if (requestedMajor !== supportedMajor) {
+    throw new ContractError(
+      `incompatible_contract_version: requested ${requested}, supported ${ADAPTER_CONTRACT_VERSION}`,
+      REASON.INCOMPATIBLE_CONTRACT,
+    );
+  }
+  return ADAPTER_CONTRACT_VERSION;
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isVersionString(value) {
+  const parts = value.split(".");
+  if (!parts.length) return false;
+  return parts.every((part) => part.length > 0 && /^[0-9]+$/.test(part));
+}