drupal-mcp-connector 2.10.1 → 2.12.0

package/src/lib/policy-promotion.js

@@ -0,0 +1,130 @@
+/**
+ * W&L-operated dual-control promotion ledger (#253 / DEV-125).
+ *
+ * The edge never mints a Sentinel HMAC seal. A promotion is an already-sealed
+ * portable document plus two distinct operator ids. Eligibility is the gate
+ * before the tenant agent may receive the artifact. Caller-supplied documents
+ * are never read here.
+ */
+
+export const POLICY_DIGEST = /^[0-9a-f]{64}$/i;
+
+export const SEAL_PREFIX = "hmac-sha256:";
+
+function tableHasKeys(table) {
+  return Object.keys(table).some((key) => {
+    const id = key.trim();
+    return id && !id.startsWith("_");
+  });
+}
+
+function uniqueApprovals(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const value of raw) {
+    const id = String(value).trim();
+    if (!id || id.startsWith("_") || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+function portableDocument(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const bag = new Map(Object.entries(raw));
+  const digest = typeof bag.get("digest") === "string"
+    ? bag.get("digest").trim().toLowerCase()
+    : "";
+  const seal = typeof bag.get("seal") === "string" ? bag.get("seal").trim() : "";
+  if (!POLICY_DIGEST.test(digest)) return null;
+  if (!seal.startsWith(SEAL_PREFIX) || seal.length <= SEAL_PREFIX.length) return null;
+  bag.set("digest", digest);
+  bag.set("seal", seal);
+  return Object.freeze(Object.fromEntries(bag));
+}
+
+/**
+ * Normalize `auth.promotions` (digest → sealed document + approvals).
+ * Comment keys and malformed rows are dropped. Duplicate operator ids in
+ * `approvals` count once. A row is eligible only with two distinct operators
+ * and a document whose claimed digest matches the map key.
+ *
+ * @param {object|null} promotions
+ * @returns {object|null}
+ */
+export function normalizePromotions(promotions) {
+  if (!promotions || typeof promotions !== "object" || Array.isArray(promotions)) {
+    return null;
+  }
+  const entries = [];
+  for (const [rawKey, value] of Object.entries(promotions)) {
+    const key = rawKey.trim().toLowerCase();
+    if (!key || key.startsWith("_") || !POLICY_DIGEST.test(key)) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const bag = new Map(Object.entries(value));
+    const document = portableDocument(bag.get("document"));
+    if (!document || document.digest !== key) continue;
+    const approvals = uniqueApprovals(bag.get("approvals"));
+    entries.push([key, Object.freeze({
+      digest: key,
+      document,
+      approvals: Object.freeze(approvals),
+      eligible: approvals.length >= 2,
+    })]);
+  }
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Whether a promotions table is in force (fail-closed even when every row
+ * is ineligible). Comment-only objects are not in force.
+ *
+ * @param {object|null} promotions
+ * @returns {boolean}
+ */
+export function promotionsRequired(promotions) {
+  if (!promotions || typeof promotions !== "object" || Array.isArray(promotions)) {
+    return false;
+  }
+  return tableHasKeys(promotions);
+}
+
+/**
+ * Eligible sealed documents ready to fan down.
+ *
+ * @param {object|null} promotions
+ * @returns {Array<{digest: string, document: object, approvals: string[]}>}
+ */
+export function eligiblePromotions(promotions) {
+  const table = normalizePromotions(promotions);
+  if (!table) return [];
+  return Object.values(table).filter((row) => row.eligible);
+}
+
+/**
+ * Look up one digest in the ledger.
+ *
+ * @param {object} params
+ * @param {string|null} [params.digest]
+ * @param {object|null} [params.promotions]
+ * @returns {{document: object|null, eligible: boolean, reason: "not_entitled"|null}}
+ */
+export function resolveEligiblePromotion({ digest = null, promotions = null } = {}) {
+  const required = promotionsRequired(promotions);
+  const table = normalizePromotions(promotions);
+  if (!table) {
+    return {
+      document: null,
+      eligible: false,
+      reason: required ? "not_entitled" : null,
+    };
+  }
+  const key = typeof digest === "string" ? digest.trim().toLowerCase() : "";
+  const record = key ? new Map(Object.entries(table)).get(key) : null;
+  if (!record || !record.eligible) {
+    return { document: null, eligible: false, reason: "not_entitled" };
+  }
+  return { document: record.document, eligible: true, reason: null };
+}

package/src/lib/principal.js

@@ -7,9 +7,9 @@
  * inbound principal and keep the existing site + source-governance filter
  * so a local operator is not hollowed out.
  *
- * Caller-supplied site, environment, tenant, target, or scope fields are
- * hints. They never become authority. Empty inbound scopes are no grants,
- * not a wildcard.
+ * Caller-supplied site, environment, tenant, target, actor, delegator,
+ * policy, digest, or scope fields are hints. They never become authority.
+ * Empty inbound scopes are no grants, not a wildcard.
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -22,6 +22,16 @@ const identityStore = new AsyncLocalStorage();
 /** Caller fields that look like a target but are never authority. */
 export const TARGET_HINT_KEYS = Object.freeze(["site", "environment", "tenant", "target"]);
 
+const ACTOR_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const POLICY_DIGEST = /^[0-9a-f]{64}$/i;
+
+function tableHasKeys(table) {
+  return Object.keys(table).some((key) => {
+    const id = key.trim();
+    return id && !id.startsWith("_");
+  });
+}
+
 /** Always discoverable; they are how an operator sees a denial. */
 export const DIAGNOSTIC_TOOLS = new Set([
   "drupal_list_sites",
@@ -104,6 +114,147 @@ export function principalHasScope(identity, scope) {
   return (identity?.scopes ?? []).includes(scope);
 }
 
+function grantNameList(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(
+    values.map((value) => String(value).trim()).filter((value) => value && !value.startsWith("_")),
+  )];
+}
+
+/**
+ * Normalize `auth.actors` (principal key → Drupal user UUID).
+ * Keys are inbound `sub` or `azp`/`clientId`. Values may be a UUID string
+ * or `{ uuid, delegators?, revoked? }`. Comment keys are dropped.
+ *
+ * @param {object|null} actors
+ * @returns {object|null}
+ */
+export function normalizeActors(actors) {
+  if (!actors || typeof actors !== "object" || Array.isArray(actors)) return null;
+  const entries = [];
+  for (const [rawKey, value] of Object.entries(actors)) {
+    const key = rawKey.trim();
+    if (!key || key.startsWith("_")) continue;
+    let uuid = "";
+    let revoked = false;
+    let delegators = [];
+    if (typeof value === "string") {
+      uuid = value.trim();
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      uuid = typeof value.uuid === "string" ? value.uuid.trim() : "";
+      revoked = value.revoked === true;
+      delegators = grantNameList(value.delegators);
+    } else {
+      continue;
+    }
+    if (!uuid || !ACTOR_UUID.test(uuid)) continue;
+    entries.push([key, Object.freeze({ uuid, revoked, delegators: Object.freeze(delegators) })]);
+  }
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Resolve the Drupal actor for this principal from server-owned grants.
+ * Caller `identity.actor` is ignored. JWT `act.sub` is a confirming hint
+ * inside `delegators`, never authority.
+ *
+ * @param {object} params
+ * @param {object|null} params.identity
+ * @param {object|null} [params.actors]
+ * @returns {{actor: string|null, delegator: string|null, required: boolean, reason: "not_entitled"|null}}
+ */
+export function resolveActor({ identity = null, actors = null } = {}) {
+  if (!actors || typeof actors !== "object" || Array.isArray(actors)) {
+    return { actor: null, delegator: null, required: false, reason: null };
+  }
+  const hasKeys = tableHasKeys(actors);
+  const table = normalizeActors(actors);
+  if (!table) {
+    return {
+      actor: null,
+      delegator: null,
+      required: hasKeys,
+      reason: hasKeys ? "not_entitled" : null,
+    };
+  }
+  const lookup = new Map(Object.entries(table));
+  const record = (identity?.sub && lookup.get(identity.sub))
+    || (identity?.clientId && lookup.get(identity.clientId))
+    || null;
+  if (!record || record.revoked) {
+    return { actor: null, delegator: null, required: true, reason: "not_entitled" };
+  }
+  const actSub = typeof identity?.actSub === "string" && identity.actSub.trim()
+    ? identity.actSub.trim()
+    : null;
+  if (actSub && !record.delegators.includes(actSub)) {
+    return { actor: null, delegator: null, required: true, reason: "not_entitled" };
+  }
+  return { actor: record.uuid, delegator: actSub, required: true, reason: null };
+}
+
+/**
+ * Normalize `auth.policies` (principal key → SHA-256 digest).
+ * Keys are inbound `sub` or `azp`/`clientId`. Values may be a digest string
+ * or `{ digest, revoked? }`. Comment keys are dropped.
+ *
+ * @param {object|null} policies
+ * @returns {object|null}
+ */
+export function normalizePolicies(policies) {
+  if (!policies || typeof policies !== "object" || Array.isArray(policies)) return null;
+  const entries = [];
+  for (const [rawKey, value] of Object.entries(policies)) {
+    const key = rawKey.trim();
+    if (!key || key.startsWith("_")) continue;
+    let digest = "";
+    let revoked = false;
+    if (typeof value === "string") {
+      digest = value.trim().toLowerCase();
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      digest = typeof value.digest === "string" ? value.digest.trim().toLowerCase() : "";
+      revoked = value.revoked === true;
+    } else {
+      continue;
+    }
+    if (!digest || !POLICY_DIGEST.test(digest)) continue;
+    entries.push([key, Object.freeze({ digest, revoked })]);
+  }
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Resolve the expected policy digest for this principal from server-owned grants.
+ * Caller `identity.policy` is ignored.
+ *
+ * @param {object} params
+ * @param {object|null} params.identity
+ * @param {object|null} [params.policies]
+ * @returns {{policy: string|null, required: boolean, reason: "not_entitled"|null}}
+ */
+export function resolvePolicy({ identity = null, policies = null } = {}) {
+  if (!policies || typeof policies !== "object" || Array.isArray(policies)) {
+    return { policy: null, required: false, reason: null };
+  }
+  const hasKeys = tableHasKeys(policies);
+  const table = normalizePolicies(policies);
+  if (!table) {
+    return {
+      policy: null,
+      required: hasKeys,
+      reason: hasKeys ? "not_entitled" : null,
+    };
+  }
+  const lookup = new Map(Object.entries(table));
+  const record = (identity?.sub && lookup.get(identity.sub))
+    || (identity?.clientId && lookup.get(identity.clientId))
+    || null;
+  if (!record || record.revoked) {
+    return { policy: null, required: true, reason: "not_entitled" };
+  }
+  return { policy: record.digest, required: true, reason: null };
+}
+
 /**
  * Site names this principal may address. Unknown names in a grant are dropped.
  *
@@ -240,7 +391,7 @@ export function describeTarget(site, source) {
  * @param {Array<object>} resolvable
  * @param {string[]} configuredNames
  * @param {object|null} [grants]
- * @returns {{sites: string[], targets: Array<{name: string, baseUrl?: string, source: string}>}}
+ * @returns {{sites: string[], targets: Array<{name: string, baseUrl?: string, source: string}>, tenants: Array<{id: string, source: string}>}}
  */
 export function visibleSiteTargets(identity, resolvable, configuredNames, grants) {
   const granted = identity ? resolveGrantedSites(identity, resolvable, grants) : resolvable;
@@ -249,12 +400,16 @@ export function visibleSiteTargets(identity, resolvable, configuredNames, grants
     : [...configuredNames];
   const byName = new Map(granted.map((site) => [site._name, site]));
   const source = identity ? "grant" : "config";
+  const tenantId = identity && typeof identity.tenant === "string" && identity.tenant
+    ? identity.tenant
+    : null;
   return {
     sites: names,
     targets: names.map((name) => {
       const site = byName.get(name);
       return site ? describeTarget(site, source) : { name, source };
     }),
+    tenants: tenantId ? [{ id: tenantId, source: "grant" }] : [],
   };
 }
 

package/src/lib/relay/agent.js

@@ -16,6 +16,7 @@
 import { connect as netConnect } from "node:net";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { createConnectorServerFactory } from "../mcp-server.js";
+import { POLICY_DIGEST } from "../policy-promotion.js";
 import { runWithIdentity } from "../principal.js";
 import { attachFramer, forwardHeaders, writeFrame } from "./frames.js";
 
@@ -35,6 +36,9 @@ import { attachFramer, forwardHeaders, writeFrame } from "./frames.js";
  * @param {?() => void} [options.onChannelClose] Called when an established
  *   channel is lost (not on deliberate `drop`/`close`), so an entry point
  *   can fail loudly instead of idling disconnected.
+ * @param {?{activate: Function}} [options.policyEnforcement] Local Sentinel
+ *   hook. `activate(document)` verifies, activates, and attests. Missing
+ *   hook fail-closes a `policy-bundle` frame (no mint on this process).
  * @param {?{recordConnect: Function}} [options.ledger]
  * @returns {object}
  */
@@ -45,6 +49,7 @@ export function createRelayAgent({
   surface,
   connectFn = netConnect,
   onChannelClose = null,
+  policyEnforcement = null,
   ledger = null,
 }) {
   if (!host || !port) {
@@ -63,6 +68,41 @@ export function createRelayAgent({
   let socket = null;
   let agentInfo = null;
 
+  async function presentBundle(activeSocket, frame) {
+    let ok = false;
+    let digest = "";
+    let reason = "no_enforcement";
+    try {
+      if (policyEnforcement && typeof policyEnforcement.activate === "function") {
+        const result = await policyEnforcement.activate(frame.document);
+        const claimed = typeof result?.digest === "string"
+          ? result.digest.trim().toLowerCase()
+          : "";
+        ok = result?.ok === true && POLICY_DIGEST.test(claimed);
+        digest = ok ? claimed : "";
+        reason = ok
+          ? ""
+          : (typeof result?.reason === "string" && result.reason.trim()
+            ? result.reason.trim().slice(0, 64)
+            : "unverified");
+      }
+    } catch {
+      ok = false;
+      digest = "";
+      reason = "activate_failed";
+    }
+    try {
+      writeFrame(activeSocket, {
+        type: "policy-bundle-ack",
+        ok,
+        digest,
+        ...(ok ? {} : { reason }),
+      });
+    } catch {
+      activeSocket.destroy();
+    }
+  }
+
   async function serveFrame(activeSocket, frame) {
     if (frame.type !== "mcp-request") return;
     if (!frame.identity || typeof frame.identity !== "object" || Array.isArray(frame.identity)) {
@@ -138,6 +178,10 @@ export function createRelayAgent({
             resolve({ ok: false, reason: frame.reason });
             return;
           }
+          if (frame.type === "policy-bundle") {
+            void presentBundle(next, frame);
+            return;
+          }
           void serveFrame(next, frame);
         });
         next.on("error", reject);