drupal-mcp-connector 2.10.0 → 2.11.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.11.0] - 2026-09-02
+
+### Security
+- **Expected policy digest on the relay edge (#250).** Optional
+  `auth.policies` maps inbound `sub` (then `azp`) to a SHA-256 digest.
+  When that table is present, non-diagnostic `tools/call` without a
+  mapping is `not_entitled` with no frames (including a call that omits
+  the tool name, and even when no agent is connected). The granted digest
+  is stamped on `identity.policy` and `correlation.policyDigest`. Caller
+  `policy` / `digest` arguments are ignored and stripped. Diagnostic
+  tools stay callable. Omitting `auth.policies` keeps the prior path.
+  Lab/loopback only — not dual-control promotion, bundle distribution, or
+  a hosted-service claim.
+- **Principal → Drupal actor mapping on the relay edge (#247).** Optional
+  `auth.actors` maps inbound `sub` (then `azp`) to a Drupal user UUID. When
+  that table is present, write-like `tools/call` without a mapping is
+  `not_entitled` with no frames. The granted actor is stamped on
+  `identity.actor`; JWT `act.sub` is a confirming hint inside `delegators`
+  and becomes `identity.delegator`. Caller `actor` / `delegator` arguments
+  and spoofable identity headers are ignored and stripped from the framed
+  body. JSON:API writes attach `relationships.uid` from the grant. The
+  northbound JWT is never the southbound Drupal credential. Omitting
+  `auth.actors` keeps writes on the site OAuth consumer's owner. Lab/loopback
+  only — not a live revision-uid or public-URL claim.
+- **Authoritative tenant routing on the relay edge (#244).** Optional
+  `auth.tenantGrants` maps inbound client id to tenant agent ids. When that
+  table is present, the edge selects the tenant from the grant (JWT `azp`),
+  not from caller `tenant` / `site` input. A hint for another tenant is
+  `not_entitled` with no frames on any tunnel. The granted tenant is stamped
+  on `identity.tenant` and on `correlation: { requestId, tenant, target,
+  source }`; the caller `tenant` argument is stripped from the framed body.
+  `drupal_list_sites` reports grant-sourced `tenants`. Installs without
+  `tenantGrants` keep the site-derived unique-agent path. Lab/loopback
+  token-resolved tenancy only — not a public hostname or path-prefix claim.
+- **Two-tenant isolation on the relay edge (#242).** The edge keeps one
+  agent-channel session per `agentId` instead of replacing the previous
+  tenant. Channel records may bind `sites` (catalog names); that bind is
+  the tenant boundary. A second unscoped agent is denied `unbound_tenant`,
+  overlapping site claims are denied `overlapping_tenant`, and fan-down
+  selects the unique agent granted to the northbound principal. Cross-tenant
+  hints still fail closed before any frame reaches the wrong process. A
+  tenant disconnect rejects only that tenant's in-flight requests. A
+  spoofed `mcp-response` from another agent cannot complete the wait.
+  A hot-reload that changes a connected agent's `sites` bind drops that
+  tunnel on the next request (`no_agent`) instead of routing on the stale
+  hello snapshot.
+  Fan-down frames carry `{ requestId, tenant, target, source }` correlation
+  and still never carry site secrets, the channel token, or the northbound JWT. A single
+  unscoped agent remains the previous compatibility path. Lab/loopback
+  proof only — not a hosted-service or public-URL claim.
+
+## [2.10.1] - 2026-08-28
+
+### Fixed
+- **Node reads include the numeric Drupal node ID (#237).** JSON:API-backed
+  `drupal_get_node` and `drupal_entity_get` results retain
+  `fields.drupal_internal__nid`, matching schema discovery while preserving
+  entity allowlists and configured field redaction. The canonical top-level
+  `id` remains the UUID.
+
+### Deprecated
+- **Loopback `shared_bearer` inbound auth (#231).** Startup warns when
+  `resolveInboundAuthMode` is `shared_bearer`, naming removal in v3.0.0.
+  Resource-server mode is silent. `npm run verify` lists the residual.
+  This is the deprecation half only; removal waits for the next major.
+
 ## [2.10.0] - 2026-08-27
 
 ### Security
@@ -1314,6 +1380,8 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.11.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.11.0
+[2.10.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.10.1
 [1.0.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v1.0.0
 [0.10.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.10.0
 [0.9.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.9.1

package/bin/drupal-mcp-edge.js

@@ -16,7 +16,10 @@
  *   MCP_CHANNEL_CREDENTIALS_FILE
  *                     Agent channel credential store (or config
  *                     relay.channelCredentialsFile). Required. JSON:
- *                     {"agents": {"<id>": {"tokenSha256": "<hex>"}}}
+ *                     {"agents": {"<id>": {"tokenSha256": "<hex>",
+ *                     "sites": ["site-name"]}}}. `sites` binds the tunnel
+ *                     to catalog names (the tenant boundary). Omit `sites`
+ *                     only for a single-agent install.
  *   MCP_EDGE_PORT     Northbound port (default: MCP_PORT / config tls.port).
  *   MCP_EDGE_AGENT_PORT
  *                     Agent channel port (default: northbound port + 1).
@@ -31,12 +34,16 @@
  *                     primary entry point).
  *
  * Config: auth.grants (client id -> [site names]) is mandatory; the edge
- * refuses to start without it.
+ * refuses to start without it. Optional auth.tenantGrants (client id ->
+ * [tenant agent ids]) makes tenant routing grant-authoritative. Optional
+ * auth.actors (sub / azp -> Drupal user UUID) maps the inbound principal
+ * to a Drupal actor for write-like tools. Optional auth.policies
+ * (sub / azp -> SHA-256 digest) is the expected signed policy on the edge.
  */
 
 import { readFileSync } from "node:fs";
 import process from "node:process";
-import { getInboundGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
+import { getInboundActors, getInboundGrants, getInboundPolicies, getInboundTenantGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
 import { resolveInboundAuthConfig } from "../src/lib/http-auth.js";
 import { createRateLimiter } from "../src/lib/rate-limit.js";
 import {
@@ -121,6 +128,9 @@ try {
   edge = await startEdge({
     auth: inboundCfg,
     grants,
+    tenantGrants: getInboundTenantGrants(),
+    actors: getInboundActors(),
+    policies: getInboundPolicies(),
     sites,
     defaultSite: config.defaultSite,
     channelCredentials: createChannelCredentialStore({ filePath: channelFile }),

package/config/config.example.json

@@ -32,6 +32,15 @@
     "grants": {
       "_comment": "Optional. Map inbound OAuth client_id (azp) to site names, e.g. \"content-agent\": [\"production\", \"staging\"]. When the map names any client, unknown clients receive no sites. Omit this object (or leave only this comment) to let every resolvable site stay visible; inbound scopes still gate the tool surface."
     },
+    "tenantGrants": {
+      "_comment": "Optional on the library path; used by drupal-mcp-edge for token-resolved tenancy. Map inbound client_id (azp) to tenant agent ids, e.g. \"content-agent\": [\"tenant-a\"]. Caller tenant/site arguments are hints checked against this grant, never authority. Omit to derive the tenant from the unique agent covering the site grant."
+    },
+    "actors": {
+      "_comment": "Optional. Map inbound sub or client_id (azp) to a Drupal user UUID for write authorship, e.g. \"content-agent\": { \"uuid\": \"11111111-1111-4111-8111-111111111111\", \"delegators\": [\"operator-1\"] }. When present, write-like tools/call without a mapping are not_entitled. JWT act.sub is a confirming hint inside delegators. Caller actor/delegator arguments are never authority. Omit to keep writes on the site OAuth consumer's owner account."
+    },
+    "policies": {
+      "_comment": "Optional. Map inbound sub or client_id (azp) to a SHA-256 digest of the expected signed Sentinel policy bundle, e.g. \"content-agent\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\". When present, non-diagnostic tools/call without a mapping are not_entitled. Caller policy/digest arguments are never authority. Omit to keep the prior path (no digest required at the edge). Local verify/activate stays on mcp_sentinel."
+    },
     "revocationFile": "",
     "introspectionUrl": "",
     "introspectionClientIdEnv": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -39,6 +39,7 @@ import {
   makeBearerCheck,
   resolveInboundAuthConfig,
   resolveInboundAuthMode,
+  inboundAuthDeprecationWarning,
   createInboundHttpsAuth,
 } from "./lib/http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-handler.js";
@@ -404,6 +405,8 @@ if (transport === "stdio") {
     console.error(`[drupal-mcp-connector] FATAL: ${inboundMode.reason}`);
     process.exit(1);
   }
+  const deprecation = inboundAuthDeprecationWarning(inboundMode.mode);
+  if (deprecation) console.error(deprecation);
 
   let checkAuth = makeBearerCheck(inboundMode.mode === "shared_bearer" ? authToken : "");
   let authenticate = null;

package/src/lib/backends/jsonapi.js

@@ -8,6 +8,7 @@
  */
 
 import { drupalFetch, drupalUploadFile } from "../drupal-fetch.js";
+import { getRequestIdentity } from "../principal.js";
 import { validateUuid, validateMachineName } from "../validate.js";
 import { parseFieldConfigObject } from "../field-definition.js";
 import { Backend } from "./backend-interface.js";
@@ -17,8 +18,9 @@ import {
   BASE_ATTRIBUTE_FIELDS,
 } from "../canonical.js";
 
-// Drupal exposes internal numeric ids under drupal_internal__* attributes;
-// these are dropped from canonical `fields` (the canonical id is the UUID).
+// Drupal exposes internal identifiers under drupal_internal__* attributes.
+// They are dropped from canonical `fields` except for the identifiers that
+// governed read/write workflows explicitly need.
 const INTERNAL_ATTR_RE = /^drupal_internal__/;
 
 // countEntities() pagination. Drupal core JSON:API returns no total in `meta`,
@@ -133,8 +135,34 @@ function applyFilter(params, { field, op = "eq", value }) {
 }
 
 /**
- * Read/write Backend adapter backed by Drupal core JSON:API.
+ * Bind JSON:API `uid` from the grant-stamped identity. Caller uid is overwritten.
+ * User entities are left unchanged. No actor claim (auth.actors not in effect
+ * for this principal) leaves relationships as-is — the prior, pre-DEV-123 path.
+ * A *present* actor claim that fails UUID validation fails closed (throws)
+ * rather than silently keeping a caller-supplied uid: resolveActor()/
+ * normalizeActors() already validate the shape before stamping identity.actor,
+ * so this should be unreachable in the normal path — it exists so a future
+ * bug upstream of this call can never downgrade into "trust the caller".
+ *
+ * @param {string} entityType
+ * @param {object|undefined} relationships
+ * @returns {object|undefined}
  */
+export function grantActorUid(entityType, relationships) {
+  if (entityType === "user") return relationships;
+  const uuid = getRequestIdentity()?.actor;
+  if (typeof uuid !== "string") return relationships;
+  validateUuid(uuid, "actor");
+  const base = relationships && typeof relationships === "object" && !Array.isArray(relationships)
+    ? relationships
+    : {};
+  return {
+    ...base,
+    uid: { data: { type: "user--user", id: uuid } },
+  };
+}
+
+/** Read/write Backend adapter backed by Drupal core JSON:API. */
 export class JsonApiBackend extends Backend {
   /** @param {object} site Site config (must include `_name`). */
   constructor(site) {
@@ -194,8 +222,9 @@ export class JsonApiBackend extends Backend {
 
   /**
    * Convert a JSON:API resource object into a CanonicalEntity. Base attributes
-   * (title/status/...) are promoted; drupal_internal__* and base fields are
-   * stripped from `fields`; relationships are normalized to canonical refs.
+   * (title/status/...) are promoted; base fields and unneeded
+   * drupal_internal__* attributes are stripped from `fields`; relationships
+   * are normalized to canonical refs.
    * @param {object} resource A JSON:API resource object.
    * @returns {import("../canonical.js").CanonicalEntity}
    */
@@ -208,10 +237,13 @@ export class JsonApiBackend extends Backend {
       Object.entries(attrs).filter(([k]) => {
         if (BASE_ATTRIBUTE_FIELDS.includes(k)) return false;
         if (INTERNAL_ATTR_RE.test(k)) {
+          // Node reads expose the numeric nid advertised by schema discovery
+          // while the UUID remains the canonical top-level id (#237).
           // Paragraph ERR attach needs the current revision id (#192).
           // Node / revisionable writes need the working vs live vid (#166).
           // Other drupal_internal__* attributes stay stripped.
-          return k === "drupal_internal__vid"
+          return (entityType === "node" && k === "drupal_internal__nid")
+            || k === "drupal_internal__vid"
             || (entityType === "paragraph" && k === "drupal_internal__revision_id");
         }
         return true;
@@ -332,7 +364,8 @@ export class JsonApiBackend extends Backend {
   async createEntity({ entityType, bundle, attributes = {}, relationships }) {
     const buildPayload = (attrs) => {
       const payload = { data: { type: `${entityType}--${bundle}`, attributes: attrs } };
-      if (relationships) payload.data.relationships = relationships;
+      const rels = grantActorUid(entityType, relationships);
+      if (rels) payload.data.relationships = rels;
       return payload;
     };
     const data = await this.writeWithModerationFallback(this.resourcePath(entityType, bundle), "POST", buildPayload, attributes);
@@ -352,7 +385,8 @@ export class JsonApiBackend extends Backend {
     validateUuid(id);
     const buildPayload = (attrs) => {
       const payload = { data: { type: `${entityType}--${bundle}`, id, attributes: attrs } };
-      if (relationships) payload.data.relationships = relationships;
+      const rels = grantActorUid(entityType, relationships);
+      if (rels) payload.data.relationships = rels;
       return payload;
     };
     let path = `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;

package/src/lib/config.js

@@ -244,6 +244,54 @@ export function getInboundGrants() {
   return entries.length ? Object.fromEntries(entries) : null;
 }
 
+/**
+ * Server-resolved inbound tenant grants keyed by OAuth client id.
+ * When present, the edge routes by tenant agent id, never by caller input.
+ * A missing or empty map means tenant is derived from site grants (compat).
+ * @returns {object|null}
+ */
+export function getInboundTenantGrants() {
+  const grants = loadConfig().auth?.tenantGrants;
+  if (!grants || typeof grants !== "object" || Array.isArray(grants)) return null;
+  const entries = Object.entries(grants)
+    .filter(([clientId, tenants]) => !clientId.startsWith("_") && Array.isArray(tenants))
+    .map(([clientId, tenants]) => [
+      clientId,
+      [...new Set(
+        tenants.map((id) => String(id).trim()).filter((id) => id && !id.startsWith("_")),
+      )],
+    ]);
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Server-resolved inbound actor map keyed by OAuth `sub` or client id.
+ * When present, write-like tools require a mapped Drupal user UUID.
+ * @returns {object|null}
+ */
+export function getInboundActors() {
+  const actors = loadConfig().auth?.actors;
+  if (!actors || typeof actors !== "object" || Array.isArray(actors)) return null;
+  const entries = Object.entries(actors)
+    .map(([key, value]) => [key.trim(), value])
+    .filter(([key]) => key && !key.startsWith("_"));
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Server-resolved inbound policy map keyed by OAuth `sub` or client id.
+ * When present, non-diagnostic tools/call require a mapped SHA-256 digest.
+ * @returns {object|null}
+ */
+export function getInboundPolicies() {
+  const policies = loadConfig().auth?.policies;
+  if (!policies || typeof policies !== "object" || Array.isArray(policies)) return null;
+  const entries = Object.entries(policies)
+    .map(([key, value]) => [key.trim(), value])
+    .filter(([key]) => key && !key.startsWith("_"));
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
 // ---------------------------------------------------------------------------
 // Auth headers — never logged, never exposed in tool responses
 // ---------------------------------------------------------------------------

package/src/lib/http-auth.js

@@ -68,7 +68,7 @@ export function scopesFromClaim(scope) {
 /**
  * Freeze a request identity from validated claims. Caller headers are not an input.
  * @param {object} claims
- * @returns {Readonly<{sub: ?string, iss: ?string, aud: string|string[]|null, scopes: readonly string[], sites: readonly string[]|null, exp: ?number, nbf: ?number, jti: ?string, clientId: ?string}>}
+ * @returns {Readonly<{sub: ?string, iss: ?string, aud: string|string[]|null, scopes: readonly string[], sites: readonly string[]|null, exp: ?number, nbf: ?number, jti: ?string, clientId: ?string, actSub: ?string}>}
  */
 export function buildIdentity(claims) {
   const scopes = scopesFromClaim(claims.scope ?? claims.scp);
@@ -95,6 +95,10 @@ export function buildIdentity(claims) {
       && (claims.client_id === undefined || claims.client_id === null)
       ? null
       : String(claims.azp ?? claims.client_id),
+    actSub: (claims.act && typeof claims.act === "object" && !Array.isArray(claims.act)
+      && typeof claims.act.sub === "string" && claims.act.sub.trim())
+      ? claims.act.sub.trim()
+      : null,
   });
 }
 
@@ -479,6 +483,26 @@ export function resolveInboundAuthMode({
   };
 }
 
+/**
+ * Startup deprecation warning for inbound auth mode `shared_bearer` (#231).
+ *
+ * Removal is the next major (v3.0.0). Resource-server and unauthenticated
+ * modes are silent. The warning names the issue and the removal version so
+ * a loopback install cannot miss the kill criterion.
+ *
+ * @param {string} mode
+ * @returns {?string} Warning text, or null when this mode is not deprecated.
+ */
+export function inboundAuthDeprecationWarning(mode) {
+  if (mode !== "shared_bearer") return null;
+  return (
+    "[drupal-mcp-connector] WARNING: inbound auth mode shared_bearer is deprecated " +
+    "and will be removed in v3.0.0 (#231). Configure an OAuth resource server " +
+    "(auth.issuer + auth.audience) or run unauthenticated loopback. " +
+    "MCP_ALLOW_UNAUTHENTICATED remains the explicit trusted-proxy opt-in."
+  );
+}
+
 /**
  * Merge config.auth with environment overrides.
  * @param {object} [cfg]

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/edge.js

@@ -1,8 +1,9 @@
 /**
- * Relay northbound edge (#232) — the DEV-294 AC4 slice.
+ * Relay northbound edge (#232, #242, #244, #247, #250) — DEV-294 AC4, DEV-122
+ * isolation, DEV-124 tenant routing, DEV-123 actor mapping, DEV-125 policy digest.
  *
  * Terminates northbound MCP over the OAuth resource server and fans requests
- * down an outbound tenant-agent channel. The edge proposes; the tenant-side
+ * down outbound tenant-agent channels. The edge proposes; the tenant-side
  * connector disposes. Policy at this seam, fail-closed from birth:
  *
  *   - `createInboundHttpsAuth` is the ONLY authentication arm. There is no
@@ -16,6 +17,11 @@
  *     before framing. The frame carries the validated identity object only.
  *   - The edge holds no site credentials: a catalog entry carrying credential
  *     material refuses startup. It cannot leak what it does not hold.
+ *   - Tunnel identity is the tenant boundary. Agent sessions are keyed by
+ *     `agentId`; channel records may bind `sites`. A second unscoped agent
+ *     or overlapping site claim is denied at hello. Fan-down selects the
+ *     unique bound agent from server-owned grants. Single unscoped agent
+ *     remains the DEV-294 compatibility path.
  *   - Stateless MCP 2026-07-28 northbound: sessionful traffic is refused and
  *     no `Mcp-Session-Id` crosses in either direction.
  *   - Revocation is per-request with no grace window, for both credential
@@ -31,7 +37,8 @@ import { createServer as createTlsServer } from "node:tls";
 import { createLocalRelay } from "../contracts/relay.js";
 import { createInboundHttpsAuth, SPOOFABLE_IDENTITY_HEADERS } from "../http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "../http-handler.js";
-import { resolveGrantedSites } from "../principal.js";
+import { isWriteLikeCall } from "../operations.js";
+import { DIAGNOSTIC_TOOLS, resolveActor, resolveGrantedSites, resolvePolicy } from "../principal.js";
 import {
   attachFramer,
   createRequestBroker,
@@ -79,6 +86,230 @@ const SITE_CREDENTIAL_KEYS = Object.freeze([
 
 const DEFAULT_FAN_DOWN_TIMEOUT_MS = 10_000;
 
+/**
+ * Normalize a channel-record `sites` list. Empty / missing means unscoped
+ * (legal only as the sole connected agent — the DEV-294 compatibility path).
+ *
+ * @param {unknown} sites
+ * @returns {string[]}
+ */
+export function boundSiteNames(sites) {
+  if (!Array.isArray(sites)) return [];
+  return sites.map(String).filter((name) => name && !name.startsWith("_"));
+}
+
+/**
+ * Decide whether a hello may join the agent-channel session table.
+ *
+ * @param {object} params
+ * @param {{agentId: string, revoked?: boolean, sites?: string[]|null}|null} params.record
+ * @param {Array<{agentId: string, sites: string[]|null}>} [params.sessions]
+ *   Currently connected agents, excluding a reconnect of the same agentId.
+ * @param {Iterable<string>} [params.catalogNames]
+ * @returns {{ok: true, sites: string[]|null}|{ok: false, reason: string}}
+ */
+export function acceptAgentHello({ record, sessions = [], catalogNames = [] } = {}) {
+  if (!record || typeof record.agentId !== "string" || !record.agentId) {
+    return { ok: false, reason: "unauthenticated" };
+  }
+  if (record.revoked) return { ok: false, reason: "revoked" };
+
+  const known = new Set([...catalogNames].map(String));
+  let incoming = boundSiteNames(record.sites);
+  if (incoming.length && known.size) {
+    incoming = incoming.filter((name) => known.has(name));
+    if (!incoming.length) return { ok: false, reason: "unbound_tenant" };
+  }
+  const incomingScoped = incoming.length > 0;
+  const others = sessions.filter((session) => session.agentId !== record.agentId);
+
+  if (others.length === 0) {
+    return { ok: true, sites: incomingScoped ? incoming : null };
+  }
+  if (!incomingScoped) return { ok: false, reason: "unbound_tenant" };
+  if (others.some((session) => !boundSiteNames(session.sites).length)) {
+    return { ok: false, reason: "unbound_tenant" };
+  }
+  const claimed = new Set(others.flatMap((session) => boundSiteNames(session.sites)));
+  if (incoming.some((name) => claimed.has(name))) {
+    return { ok: false, reason: "overlapping_tenant" };
+  }
+  return { ok: true, sites: incoming };
+}
+
+/**
+ * Pick the unique tenant agent this principal may use.
+ *
+ * @param {object} params
+ * @param {string[]} params.grantedSiteNames
+ * @param {string|null} [params.targetName]
+ * @param {Array<{agentId: string, sites: string[]|null}>} params.sessions
+ * @returns {{session: object|null, reason: "not_entitled"|"no_agent"|null}}
+ */
+export function selectTenantSession({
+  grantedSiteNames = [],
+  targetName = null,
+  sessions = [],
+} = {}) {
+  if (!grantedSiteNames.length) return { session: null, reason: "not_entitled" };
+  if (targetName && !grantedSiteNames.includes(targetName)) {
+    return { session: null, reason: "not_entitled" };
+  }
+  const needed = targetName ? [targetName] : [...grantedSiteNames];
+  if (!sessions.length) return { session: null, reason: "no_agent" };
+
+  const scoped = [];
+  const unscoped = [];
+  for (const session of sessions) {
+    if (boundSiteNames(session.sites).length) scoped.push(session);
+    else unscoped.push(session);
+  }
+
+  if (unscoped.length && scoped.length) {
+    return { session: null, reason: "no_agent" };
+  }
+  if (unscoped.length === 1 && sessions.length === 1) {
+    return { session: unscoped[0], reason: null };
+  }
+  if (unscoped.length > 1) return { session: null, reason: "no_agent" };
+
+  const matches = scoped.filter((session) => {
+    const names = new Set(boundSiteNames(session.sites));
+    return needed.every((name) => names.has(name));
+  });
+  if (matches.length === 1) return { session: matches[0], reason: null };
+  if (matches.length > 1) return { session: null, reason: "not_entitled" };
+
+  const partial = scoped.filter((session) => {
+    const names = new Set(boundSiteNames(session.sites));
+    return needed.some((name) => names.has(name));
+  });
+  if (partial.length > 0 && needed.length > 1) {
+    return { session: null, reason: "not_entitled" };
+  }
+  return { session: null, reason: "no_agent" };
+}
+
+/**
+ * Resolve tenant and target from server-owned grants. Caller `tenant` is a
+ * confirming hint inside the grant, never authority. When `tenantGrants` is
+ * omitted, tenant is derived from the unique agent covering the site grant
+ * (DEV-122 / DEV-294 compatibility).
+ *
+ * @param {object} params
+ * @param {object|null} params.identity
+ * @param {string|null} [params.callerTenant]
+ * @param {object|null} [params.tenantGrants]
+ * @param {string[]} params.grantedSiteNames
+ * @param {string|null} [params.targetName]
+ * @param {Array<{agentId: string, sites: string[]|null}>} params.sessions
+ * @returns {{session: object|null, tenant: string|null, target: string|null, source: string, reason: "not_entitled"|"no_agent"|null}}
+ */
+export function resolveTenantRoute({
+  identity,
+  callerTenant = null,
+  tenantGrants = null,
+  grantedSiteNames = [],
+  targetName = null,
+  sessions = [],
+} = {}) {
+  if (tenantGrants) {
+    const listed = identity?.clientId
+      ? new Map(Object.entries(tenantGrants)).get(identity.clientId)
+      : undefined;
+    const grantedTenants = grantIds(listed);
+    if (!grantedTenants.length) {
+      return {
+        session: null, tenant: null, target: targetName, source: "grant", reason: "not_entitled",
+      };
+    }
+    if (callerTenant && !grantedTenants.includes(callerTenant)) {
+      return {
+        session: null, tenant: null, target: targetName, source: "grant", reason: "not_entitled",
+      };
+    }
+    if (!callerTenant && grantedTenants.length > 1) {
+      return {
+        session: null, tenant: null, target: targetName, source: "grant", reason: "not_entitled",
+      };
+    }
+    const tenant = callerTenant || grantedTenants[0];
+    const session = sessions.find((entry) => entry.agentId === tenant) ?? null;
+    if (!session) {
+      return {
+        session: null, tenant, target: targetName, source: "grant", reason: "no_agent",
+      };
+    }
+    const tenantSites = boundSiteNames(session.sites);
+    const allowed = tenantSites.length
+      ? grantedSiteNames.filter((name) => tenantSites.includes(name))
+      : grantedSiteNames;
+    if (targetName && !allowed.includes(targetName)) {
+      return {
+        session: null, tenant, target: targetName, source: "grant", reason: "not_entitled",
+      };
+    }
+    if (!targetName && grantedSiteNames.length && allowed.length === 0) {
+      return {
+        session: null, tenant, target: targetName, source: "grant", reason: "not_entitled",
+      };
+    }
+    return { session, tenant, target: targetName, source: "grant", reason: null };
+  }
+
+  const selected = selectTenantSession({ grantedSiteNames, targetName, sessions });
+  return {
+    session: selected.session,
+    tenant: selected.session?.agentId ?? null,
+    target: targetName,
+    source: "grant",
+    reason: selected.reason,
+  };
+}
+
+function callerTenantHint(args = {}) {
+  const value = new Map(Object.entries(args ?? {})).get("tenant");
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+const CALLER_HINT_KEYS = Object.freeze(["tenant", "actor", "delegator", "policy", "digest"]);
+
+function stripCallerHints(body) {
+  const args = body?.params?.arguments;
+  if (!args || typeof args !== "object" || Array.isArray(args)) return body;
+  const bag = new Map(Object.entries(args));
+  let changed = false;
+  for (const key of CALLER_HINT_KEYS) {
+    if (bag.has(key)) {
+      bag.delete(key);
+      changed = true;
+    }
+  }
+  if (!changed) return body;
+  return { ...body, params: { ...body.params, arguments: Object.fromEntries(bag) } };
+}
+
+function identityWithGrant(identity, { tenant, actor = null, delegator = null, policy = null }) {
+  const bag = new Map(Object.entries(identity ?? {}));
+  for (const key of ["actor", "delegator", "policy", "digest"]) bag.delete(key);
+  bag.set("tenant", tenant);
+  if (actor) bag.set("actor", actor);
+  if (delegator) bag.set("delegator", delegator);
+  if (policy) bag.set("policy", policy);
+  return Object.freeze(Object.fromEntries(bag));
+}
+
+/**
+ * Canonical form of a tenant site bind. Null and empty both mean unscoped.
+ *
+ * @param {unknown} sites
+ * @returns {string}
+ */
+export function siteBindingKey(sites) {
+  const names = boundSiteNames(sites);
+  return names.length ? names.slice().sort().join("\0") : "";
+}
+
 /** Startup refusals: configuration that must not become a listener. */
 export class EdgeStartupError extends Error {
   constructor(message) {
@@ -110,14 +341,17 @@ export function fanDownHeaders(headers = {}) {
  * Hot-reloaded agent channel credential store.
  *
  * File shape: `{ "agents": { "<agentId>": { "tokenSha256": "<hex>",
- * "revoked": false } } }`. The edge stores only SHA-256 digests — never a raw
- * channel token. A missing or unreadable file denies every lookup (a
- * credential table that cannot be read authorizes nobody), and the file is
- * re-read when its mtime changes so a revoke needs no restart.
+ * "sites": ["site-name"], "revoked": false } } }`. The edge stores only
+ * SHA-256 digests — never a raw channel token. `sites` binds the tunnel to
+ * catalog names (the tenant boundary). Omitted `sites` is unscoped and is
+ * only accepted as the sole connected agent. A missing or unreadable file
+ * denies every lookup (a credential table that cannot be read authorizes
+ * nobody), and the file is re-read when its mtime changes so a revoke needs
+ * no restart.
  *
  * @param {object} options
  * @param {string} options.filePath
- * @returns {{lookup: (token: string) => {agentId: string, revoked: boolean}|null}}
+ * @returns {{lookup: (token: string) => {agentId: string, revoked: boolean, sites: string[]|null}|null}}
  */
 export function createChannelCredentialStore({
   filePath,
@@ -146,6 +380,7 @@ export function createChannelCredentialStore({
           agentId,
           tokenSha256: entry.tokenSha256.toLowerCase(),
           revoked: entry.revoked === true,
+          sites: Array.isArray(entry.sites) ? boundSiteNames(entry.sites) : null,
         }));
       cache = { mtimeMs: info.mtimeMs, agents, denyAll: false };
     } catch {
@@ -166,7 +401,7 @@ export function createChannelCredentialStore({
       for (const agent of agents) {
         const expected = Buffer.from(agent.tokenSha256, "utf8");
         if (digest.length === expected.length && timingSafeEqual(digest, expected)) {
-          return { agentId: agent.agentId, revoked: agent.revoked };
+          return { agentId: agent.agentId, revoked: agent.revoked, sites: agent.sites };
         }
       }
       return null;
@@ -178,11 +413,18 @@ function isLoopback(host) {
   return host === "127.0.0.1" || host === "::1" || host === "localhost";
 }
 
+function grantIds(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(
+    values.map((value) => String(value).trim()).filter((value) => value && !value.startsWith("_")),
+  )];
+}
+
 function normalizeGrants(grants) {
   if (!grants || typeof grants !== "object" || Array.isArray(grants)) return null;
   const entries = Object.entries(grants)
     .filter(([clientId, sites]) => !clientId.startsWith("_") && Array.isArray(sites))
-    .map(([clientId, sites]) => [clientId, sites.map(String)]);
+    .map(([clientId, sites]) => [clientId, grantIds(sites)]);
   return entries.length ? Object.fromEntries(entries) : null;
 }
 
@@ -222,6 +464,11 @@ function jsonResponse(res, status, body) {
  * @param {{issuer: string, audience: string}} options.auth Inbound
  *   resource-server config (`resolveInboundAuthConfig` shape). Mandatory.
  * @param {object} options.grants Non-empty client-id → site-name grant table.
+ * @param {object|null} [options.tenantGrants] Optional client-id → tenant
+ *   agent-id table. When present, tenant routing is grant-authoritative.
+ * @param {object|null} [options.actors] Optional principal → Drupal actor
+ *   table (`sub` / `azp` → `{ uuid, delegators? }`). When present, write-like
+ *   tools/call require a mapping.
  * @param {Array<{_name: string}>} options.sites Credential-free catalog.
  * @param {string} [options.defaultSite]
  * @param {{lookup: Function}} options.channelCredentials Agent channel store.
@@ -240,6 +487,9 @@ function jsonResponse(res, status, body) {
 export async function startEdge({
   auth,
   grants,
+  tenantGrants = null,
+  actors = null,
+  policies = null,
   sites,
   defaultSite,
   channelCredentials,
@@ -268,6 +518,13 @@ export async function startEdge({
       + "The library's all-sites fallback does not apply to this entry point.",
     );
   }
+  const tenantGrantTable = normalizeGrants(tenantGrants);
+  const actorTable = actors && typeof actors === "object" && !Array.isArray(actors)
+    ? actors
+    : null;
+  const policyTable = policies && typeof policies === "object" && !Array.isArray(policies)
+    ? policies
+    : null;
   if (typeof channelCredentials?.lookup !== "function") {
     throw new EdgeStartupError(
       "Relay edge requires an agent channel credential store; without one no "
@@ -293,7 +550,9 @@ export async function startEdge({
   const targetRelay = createLocalRelay({ sites: catalog, grants: grantTable, defaultSite });
   const broker = createRequestBroker({ timeoutMs: fanDownTimeoutMs });
 
-  let session = null;
+  /** @type {Map<string, {socket: object, token: string, agentId: string, sites: string[]|null}>} */
+  const sessions = new Map();
+  const catalogNames = catalog.map((site) => site._name);
 
   const channelServer = (hasTls ? createTlsServer(tls) : createNetServer())
     .on("connection", handleChannelSocket)
@@ -303,35 +562,49 @@ export async function startEdge({
     // Plain server emits "connection"; the TLS server emits both "connection"
     // (raw) and "secureConnection" (cleartext). Attach once, post-handshake.
     if (hasTls && !socket.encrypted) return;
+    let agentId = null;
     attachFramer(socket, (frame) => {
       if (frame.type === "hello") {
         const record = channelCredentials.lookup(frame.token);
-        if (!record) {
-          writeFrame(socket, { type: "denied", reason: "unauthenticated" });
-          socket.end();
-          return;
-        }
-        if (record.revoked) {
-          writeFrame(socket, { type: "denied", reason: "revoked" });
+        const others = [...sessions.values()].filter((entry) => entry.socket !== socket);
+        const decision = acceptAgentHello({
+          record,
+          sessions: others,
+          catalogNames,
+        });
+        if (!decision.ok) {
+          writeFrame(socket, { type: "denied", reason: decision.reason });
           socket.end();
           return;
         }
-        if (session && session.socket !== socket) session.socket.destroy();
-        session = { socket, token: frame.token, agentId: record.agentId };
-        writeFrame(socket, { type: "hello-ok", agent: { agentId: record.agentId } });
+        const existing = sessions.get(record.agentId);
+        if (existing && existing.socket !== socket) existing.socket.destroy();
+        agentId = record.agentId;
+        sessions.set(agentId, {
+          socket,
+          token: frame.token,
+          agentId,
+          sites: decision.sites,
+        });
+        writeFrame(socket, { type: "hello-ok", agent: { agentId } });
         return;
       }
       if (frame.type === "mcp-response") {
-        broker.settle(frame);
+        if (!agentId) {
+          socket.destroy();
+          return;
+        }
+        broker.settle(frame, { owner: agentId });
         return;
       }
       // Any other frame type on the agent channel is a protocol violation.
       socket.destroy();
     });
     socket.on("close", () => {
-      if (session?.socket === socket) {
-        session = null;
-        broker.rejectAll(new Error("Relay agent channel closed."));
+      const current = agentId ? sessions.get(agentId) : null;
+      if (current?.socket === socket) {
+        sessions.delete(agentId);
+        broker.rejectByOwner(agentId, new Error("Relay agent channel closed."));
       }
     });
   }
@@ -352,38 +625,92 @@ export async function startEdge({
       jsonResponse(res, 403, { error: "not_entitled" });
       return;
     }
+    const args = body?.params?.arguments ?? {};
+    const callerTenant = callerTenantHint(args);
+    const siteArgs = { ...args };
+    delete siteArgs.tenant;
+    let targetName = null;
     if (body?.method === "tools/call") {
       try {
-        targetRelay.resolve(identity, body?.params?.arguments ?? {});
+        targetName = targetRelay.resolve(identity, siteArgs).name;
       } catch {
         jsonResponse(res, 403, { error: "not_entitled" });
         return;
       }
     }
 
-    if (!session) {
-      jsonResponse(res, 503, { error: "no_agent" });
+    const mapped = resolveActor({ identity, actors: actorTable });
+    const boundPolicy = resolvePolicy({ identity, policies: policyTable });
+    const isCall = body?.method === "tools/call";
+    const toolName = isCall && typeof body?.params?.name === "string" && body.params.name.trim()
+      ? body.params.name.trim()
+      : null;
+    if (mapped.required && mapped.reason && isCall && (!toolName || isWriteLikeCall(toolName, args))) {
+      jsonResponse(res, 403, { error: "not_entitled" });
+      return;
+    }
+    if (
+      boundPolicy.required && boundPolicy.reason && isCall
+      && (!toolName || !DIAGNOSTIC_TOOLS.has(toolName))
+    ) {
+      jsonResponse(res, 403, { error: "not_entitled" });
+      return;
+    }
+
+    const selected = resolveTenantRoute({
+      identity,
+      callerTenant,
+      tenantGrants: tenantGrantTable,
+      grantedSiteNames: granted.map((site) => site._name),
+      targetName,
+      sessions: [...sessions.values()],
+    });
+    if (!selected.session) {
+      const entitled = selected.reason === "not_entitled";
+      jsonResponse(res, entitled ? 403 : 503, {
+        error: entitled ? "not_entitled" : "no_agent",
+      });
       return;
     }
-    const record = channelCredentials.lookup(session.token);
+    const record = channelCredentials.lookup(selected.session.token);
     if (!record || record.revoked) {
       jsonResponse(res, 403, { error: "revoked", bound: EDGE_REVOCATION_BOUND.name });
       return;
     }
+    if (siteBindingKey(record.sites) !== siteBindingKey(selected.session.sites)) {
+      selected.session.socket.destroy();
+      jsonResponse(res, 503, { error: "no_agent" });
+      return;
+    }
 
     const id = randomUUID();
-    const waited = broker.track(id);
-    const wrote = writeFrame(session.socket, {
+    const waited = broker.track(id, { owner: selected.session.agentId });
+    const routedIdentity = identityWithGrant(identity, {
+      tenant: selected.tenant,
+      actor: mapped.actor,
+      delegator: mapped.delegator,
+      policy: boundPolicy.policy,
+    });
+    const wrote = writeFrame(selected.session.socket, {
       type: "mcp-request",
       id,
       method: req.method,
       url: "/mcp",
       headers: fanDownHeaders(req.headers),
-      identity,
-      body,
+      identity: routedIdentity,
+      body: stripCallerHints(body),
+      correlation: {
+        requestId: id,
+        tenant: selected.tenant,
+        target: selected.target,
+        source: selected.source,
+        ...(mapped.actor ? { actor: mapped.actor } : {}),
+        ...(mapped.delegator ? { delegator: mapped.delegator } : {}),
+        ...(boundPolicy.policy ? { policyDigest: boundPolicy.policy } : {}),
+      },
     });
     if (!wrote) {
-      broker.settle({ id, status: 503 });
+      broker.settle({ id, status: 503 }, { owner: selected.session.agentId });
       jsonResponse(res, 503, { error: "no_agent" });
       return;
     }
@@ -446,16 +773,20 @@ export async function startEdge({
     agentPort: channelAddr.port,
     resourceMetadataUrl: inbound.resourceMetadataUrl,
     get hasAgent() {
-      return Boolean(session);
+      return sessions.size > 0;
     },
     get agentId() {
-      return session?.agentId ?? null;
+      if (sessions.size !== 1) return null;
+      return sessions.keys().next().value;
+    },
+    get agentIds() {
+      return [...sessions.keys()];
     },
     async close() {
       if (closed) return;
       closed = true;
-      session?.socket.destroy();
-      session = null;
+      for (const entry of sessions.values()) entry.socket.destroy();
+      sessions.clear();
       broker.rejectAll(new Error("Relay edge closed."));
       await closeServer(channelServer);
       await closeServer(northServer);

package/src/lib/relay/frames.js

@@ -118,13 +118,25 @@ export function writeFrame(socket, frame) {
 /**
  * Correlate mcp-request ids with their mcp-response frames.
  *
+ * Optional `owner` binds a tracked id to one tenant agent. A response from a
+ * different owner is ignored (cross-tenant injection cannot complete the
+ * wait). Disconnecting one owner rejects only that owner's pending ids.
+ *
  * @param {object} [options]
  * @param {number} [options.timeoutMs] Per-request wait bound.
- * @returns {{size: number, track: (id: string) => Promise<object>, settle: (frame: {id?: string}) => boolean, rejectAll: (error: Error) => void}}
+ * @returns {object}
  */
 export function createRequestBroker({ timeoutMs = 10_000 } = {}) {
   const pending = new Map();
 
+  function drop(id, apply) {
+    const waiter = pending.get(id);
+    if (!waiter) return false;
+    pending.delete(id);
+    apply(waiter);
+    return true;
+  }
+
   return {
     get size() {
       return pending.size;
@@ -132,9 +144,10 @@ export function createRequestBroker({ timeoutMs = 10_000 } = {}) {
 
     /**
      * @param {string} id
+     * @param {{owner?: string|null}} [options]
      * @returns {Promise<object>} Resolves with the matching response frame.
      */
-    track(id) {
+    track(id, { owner = null } = {}) {
       return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
           pending.delete(id);
@@ -142,6 +155,7 @@ export function createRequestBroker({ timeoutMs = 10_000 } = {}) {
         }, timeoutMs);
         timer.unref?.();
         pending.set(id, {
+          owner,
           resolve(frame) {
             clearTimeout(timer);
             resolve(frame);
@@ -156,24 +170,36 @@ export function createRequestBroker({ timeoutMs = 10_000 } = {}) {
 
     /**
      * @param {{id?: string}} frame
+     * @param {{owner?: string|null}} [options]
      * @returns {boolean} True when a tracked request was resolved.
      */
-    settle(frame) {
+    settle(frame, { owner = null } = {}) {
       if (typeof frame?.id !== "string") return false;
       const waiter = pending.get(frame.id);
       if (!waiter) return false;
-      pending.delete(frame.id);
-      waiter.resolve(frame);
-      return true;
+      if (typeof waiter.owner === "string" && waiter.owner !== owner) {
+        return false;
+      }
+      return drop(frame.id, (entry) => entry.resolve(frame));
+    },
+
+    /**
+     * @param {string} owner
+     * @param {Error} error
+     */
+    rejectByOwner(owner, error) {
+      for (const [id, waiter] of [...pending]) {
+        if (waiter.owner !== owner) continue;
+        drop(id, (entry) => entry.reject(error));
+      }
     },
 
     /**
      * @param {Error} error
      */
     rejectAll(error) {
-      for (const [id, waiter] of pending) {
-        pending.delete(id);
-        waiter.reject(error);
+      for (const [id] of [...pending]) {
+        drop(id, (entry) => entry.reject(error));
       }
     },
   };

package/src/lib/verify.js

@@ -75,6 +75,16 @@ export const RESIDUALS = [
       "responsibility; the connector reads secrets from the environment and never " +
       "stores them.",
   },
+  {
+    id: "loopback_shared_bearer",
+    status: "managed",
+    detail:
+      "Loopback MCP_AUTH_TOKEN (inbound mode shared_bearer) still ships. It is " +
+      "deprecated as of this release and will be removed in v3.0.0 (#231). " +
+      "Network-facing product paths already refuse it. MCP_ALLOW_UNAUTHENTICATED " +
+      "is a separate named residual: an explicit trusted-proxy opt-in, not a " +
+      "shared credential, and is not retired by #231.",
+  },
 ];
 
 /** Hostname suffixes reserved for documentation and testing (RFC 2606/6761). */

package/src/tools/site.js

@@ -47,7 +47,7 @@ async function listContentTypes({ site: siteName }) {
  * List named sites this principal may address. No backend call and no credentials.
  * `sites` stays a name list for compatibility; `targets` is the authoritative
  * resolved-target record.
- * @returns {Promise<{sites: string[], targets: Array<object>}>}
+ * @returns {Promise<{sites: string[], targets: Array<object>, tenants: Array<object>}>}
  */
 async function listConfiguredSites() {
   const names = listSiteNames();