drupal-mcp-connector 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.13.0] - 2026-09-02
+
+### Security
+- **Attributable usage, quotas, and abuse signals on the relay edge (#256).**
+  Optional usage ledger (`MCP_EDGE_USAGE_MAX_RECORDS` / `relay.usage`)
+  records every edge decision (allow or deny) and every fan-down receipt
+  against the grant-resolved tenant and the validated principal, carrying
+  the frame's `requestId`, a `decisionId`, the bound `policyDigest`, and
+  measured cost signals (units, bytes, duration). Optional `auth.quotas`
+  (tenant / principal request windows plus an abuse lock) fails closed at
+  the edge: an unlisted tenant or principal is `not_entitled`, an exhausted
+  window is `429 quota_exceeded` with `Retry-After`, and a principal that
+  keeps earning refusals is `429 abuse_locked` — all with zero frames on any
+  tunnel. A shared tenant window running out never feeds an individual
+  principal's lock; a quota table the edge cannot read refuses startup and
+  names the offending path. A response the listener cannot relay is
+  `502 fan_down_failed` with a `failed` receipt, and a metering failure
+  never changes a verdict. `GET /usage` serves the caller's own tenant
+  partition (tenant from `auth.tenantGrants`; any other tenant is
+  `not_entitled` with no records) with a reconciliation naming `missing`,
+  `duplicate`, and `uncertain` chains; unmatched response frames are
+  recorded against the sending tunnel. Omitting both keeps the 2.12.0 path.
+  Lab/loopback only — measured usage, not pricing, billing, a hosted
+  metering sink, or a hosted-service claim.
+
+## [2.12.0] - 2026-09-02
+
+### Security
+- **W&L-operated policy-bundle promotion on the relay edge (#253).** Optional
+  `auth.promotions` maps a SHA-256 digest to a sealed portable document plus
+  two distinct operator ids. Eligible documents fan down the tenant-agent
+  channel after hello; the agent presents them to local enforcement
+  (verify / activate / attest). When the table is present, non-diagnostic
+  `tools/call` requires the bound `auth.policies` digest **and** a matching
+  agent attestation. The edge never mints a Sentinel HMAC key. Omitting
+  `auth.promotions` keeps the digest-only path. Lab/loopback only — not
+  tenant self-service or a hosted-service claim.
+
 ## [2.11.0] - 2026-09-02
 
 ### Security
@@ -1380,6 +1418,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.13.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.0
+[2.12.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.12.0
 [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

package/bin/drupal-mcp-edge.js

@@ -32,6 +32,13 @@
  *   MCP_RATE_LIMIT / MCP_RATE_WINDOW_SEC
  *                     Northbound /mcp rate limit (same defaults as the
  *                     primary entry point).
+ *   MCP_EDGE_USAGE_MAX_RECORDS
+ *                     Positive integer enables the in-process usage ledger
+ *                     (or config relay.usage.maxRecords). Every decision and
+ *                     receipt is recorded per tenant and principal, and
+ *                     GET /usage serves the caller's own tenant partition.
+ *                     Unset: nothing is recorded and /usage is 404. Set but
+ *                     unreadable: fatal.
  *
  * Config: auth.grants (client id -> [site names]) is mandatory; the edge
  * refuses to start without it. Optional auth.tenantGrants (client id ->
@@ -39,13 +46,29 @@
  * 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.
+ * Optional auth.promotions (digest -> sealed document + two operator ids)
+ * is the W&L-operated dual-control ledger; the edge fans eligible bundles
+ * to the tenant agent and requires a matching local attestation. Optional
+ * auth.quotas (tenant / principal request windows plus an abuse lock)
+ * fails closed at the edge with zero frames on any refusal; a table the
+ * edge cannot read refuses startup.
  */
 
 import { readFileSync } from "node:fs";
 import process from "node:process";
-import { getInboundActors, getInboundGrants, getInboundPolicies, getInboundTenantGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
+import {
+  getInboundActors,
+  getInboundGrants,
+  getInboundPolicies,
+  getInboundPromotions,
+  getInboundQuotas,
+  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 { createUsageLedger } from "../src/lib/usage.js";
 import {
   createChannelCredentialStore,
   startEdge,
@@ -123,6 +146,29 @@ const rateLimit = rateLimitEnv === undefined || rateLimitEnv === ""
   ? rateLimitDefault
   : Number(rateLimitEnv);
 
+// Usage ledger (#256): opt-in, in-process, bounded. A restart clears it.
+// A value that is set but unreadable is fatal: the operator asked for
+// metering, and silently running without it would be a lie.
+const usageEnv = process.env.MCP_EDGE_USAGE_MAX_RECORDS;
+const usageRaw = usageEnv !== undefined && usageEnv !== ""
+  ? usageEnv
+  : config.relay?.usage?.maxRecords;
+let usageMaxRecords = 0;
+if (usageRaw !== undefined && usageRaw !== null) {
+  const parsed = typeof usageRaw === "string" && /^[0-9]+$/.test(usageRaw.trim())
+    ? Number(usageRaw.trim())
+    : usageRaw;
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    fatal(
+      "MCP_EDGE_USAGE_MAX_RECORDS (or relay.usage.maxRecords) must be a positive "
+      + `integer; got ${JSON.stringify(usageRaw)}. Unset it to run without the usage ledger.`,
+    );
+  }
+  usageMaxRecords = parsed;
+}
+const usage = usageMaxRecords > 0 ? createUsageLedger({ maxRecords: usageMaxRecords }) : null;
+const quotas = getInboundQuotas();
+
 let edge;
 try {
   edge = await startEdge({
@@ -131,6 +177,9 @@ try {
     tenantGrants: getInboundTenantGrants(),
     actors: getInboundActors(),
     policies: getInboundPolicies(),
+    promotions: getInboundPromotions(),
+    quotas,
+    usage,
     sites,
     defaultSite: config.defaultSite,
     channelCredentials: createChannelCredentialStore({ filePath: channelFile }),
@@ -158,3 +207,11 @@ if (rateLimit > 0) {
     `[drupal-mcp-edge] Rate limiting: ${rateLimit} req / ${rateWindowSec}s per client IP on /mcp.`,
   );
 }
+if (usage) {
+  console.error(
+    `[drupal-mcp-edge] Usage ledger: in-process, ${usageMaxRecords} records max; GET /usage serves one tenant partition.`,
+  );
+}
+if (quotas) {
+  console.error("[drupal-mcp-edge] Quotas: auth.quotas in force; unlisted tenants / principals are refused.");
+}

package/config/config.example.json

@@ -41,6 +41,12 @@
     "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."
     },
+    "promotions": {
+      "_comment": "Optional W&L-operated dual-control ledger. Map a SHA-256 digest to { document, approvals } where document is the sealed portable Sentinel bundle (claims + digest + hmac-sha256 seal) and approvals is two distinct operator ids. When present, the edge fans eligible documents to the tenant agent; non-diagnostic tools/call require a matching local attestation. The edge never mints a seal. Omit to keep the digest-only path. Tenant self-service is not this table."
+    },
+    "quotas": {
+      "_comment": "Optional, drupal-mcp-edge only. { tenants: { \"<agent id>\": { requests, windowSec } }, principals: { \"<sub or client_id>\": { requests, windowSec } }, abuse: { denials, windowSec, lockSec } }. When a tenants or principals table names any id, an id without a row is not_entitled; an exhausted window is 429 quota_exceeded with Retry-After; a principal that earns `denials` refusals inside windowSec is 429 abuse_locked for lockSec. Every refusal is zero frames on any tunnel. A shared tenant window running out never feeds an individual principal's abuse lock. A table the edge cannot read refuses startup and names the offending path. Omit to keep the prior path (no quota at the edge). Counting is measured usage, not pricing."
+    },
     "revocationFile": "",
     "introspectionUrl": "",
     "introspectionClientIdEnv": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.11.0",
+  "version": "2.13.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/lib/config.js

@@ -292,6 +292,46 @@ export function getInboundPolicies() {
   return entries.length ? Object.fromEntries(entries) : null;
 }
 
+/**
+ * W&L-operated dual-control promotion ledger keyed by SHA-256 digest.
+ * When present, the edge fans eligible sealed documents to the tenant agent.
+ * @returns {object|null}
+ */
+export function getInboundPromotions() {
+  const promotions = loadConfig().auth?.promotions;
+  if (!promotions || typeof promotions !== "object" || Array.isArray(promotions)) {
+    return null;
+  }
+  const entries = Object.entries(promotions)
+    .map(([key, value]) => [key.trim(), value])
+    .filter(([key]) => key && !key.startsWith("_"));
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Tenant / principal quota table plus abuse lock (`auth.quotas`).
+ * When present, the relay edge fails closed: a tenant or principal without
+ * a row is refused, exhausted windows and locked principals are refused,
+ * and a table the edge cannot read refuses startup. Validation lives in
+ * usage.js (`normalizeQuotas`).
+ * @returns {object|null|unknown} Null when omitted or comment-only; the
+ *   comment-stripped table when it is an object; otherwise the configured
+ *   value unchanged (a string, array, number, ...) so `startEdge()` refuses
+ *   to start on it instead of running unmetered.
+ */
+export function getInboundQuotas() {
+  const quotas = loadConfig().auth?.quotas;
+  if (quotas === undefined || quotas === null) return null;
+  // A present value that is not an object is passed through unchanged so
+  // the edge refuses to start on it (usage.js normalizeQuotas names it);
+  // returning null here would silently run without quotas.
+  if (typeof quotas !== "object" || Array.isArray(quotas)) return quotas;
+  const entries = Object.entries(quotas)
+    .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/policy-enforcement.js

@@ -0,0 +1,268 @@
+/**
+ * Tenant-side local policy enforcement (#253 / DEV-125).
+ *
+ * Loopback stand-in for mcp_sentinel `McpPolicyBundleRegistry`: mint / verify
+ * / activate / simulate / revoke / rollback / emergency deny. The relay edge
+ * never receives the signing key and never calls mint. A missing key cannot
+ * mint, verify, or activate — emergency deny still arms a deny floor without
+ * minting new authority.
+ */
+
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { SEAL_PREFIX } from "./policy-promotion.js";
+
+export const POLICY_BUNDLE_VERSION = 1;
+
+export const DEFAULT_BUNDLE_TTL = 86400 * 30;
+
+export const EMERGENCY_DENY = "*";
+
+export const EMERGENCY_DIGEST = "emergency-deny";
+
+function normalize(value) {
+  if (value === null || typeof value === "string" || typeof value === "number"
+    || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(normalize);
+  if (value && typeof value === "object") {
+    const source = new Map(Object.entries(value));
+    const bag = new Map();
+    for (const key of [...source.keys()].sort()) {
+      bag.set(key, normalize(source.get(key)));
+    }
+    return Object.fromEntries(bag);
+  }
+  throw new TypeError("Policy bundle claims may only contain scalars, lists and maps.");
+}
+
+/**
+ * Canonical JSON of claims (HMAC / digest input). Maps are key-sorted;
+ * lists keep caller order. Matches mcp_sentinel `McpPolicyBundle::canonicalJson`.
+ *
+ * @param {object} claims
+ * @returns {string}
+ */
+export function canonicalJson(claims) {
+  return JSON.stringify(normalize(claims));
+}
+
+/**
+ * Hex SHA-256 of the canonical claims.
+ *
+ * @param {object} claims
+ * @returns {string}
+ */
+export function digestOf(claims) {
+  return createHash("sha256").update(canonicalJson(claims)).digest("hex");
+}
+
+function safeEqual(left, right) {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+function deniedOperationsOf(claims) {
+  const denials = new Map(Object.entries(claims ?? {})).get("denials");
+  if (!denials || typeof denials !== "object" || Array.isArray(denials)) return [];
+  const ops = new Map(Object.entries(denials)).get("operations");
+  if (!Array.isArray(ops)) return [];
+  return ops.map(String);
+}
+
+function bundleFrom(claims, digest, seal) {
+  return Object.freeze({
+    claims,
+    digest,
+    seal,
+    version: () => Number(new Map(Object.entries(claims)).get("v") ?? 0),
+    expires: () => Number(new Map(Object.entries(claims)).get("expires") ?? 0),
+    deniedOperations: () => deniedOperationsOf(claims),
+    denies: (operation) => deniedOperationsOf(claims).includes(operation),
+    isExpired: (now) => {
+      const expires = Number(new Map(Object.entries(claims)).get("expires") ?? 0);
+      return expires > 0 && now >= expires;
+    },
+    toArray: () => ({ ...claims, digest, seal }),
+  });
+}
+
+/**
+ * In-process local enforcement used by the tenant agent in the loopback lab.
+ *
+ * @param {object} [options]
+ * @param {string|null} [options.signingKey] HMAC material. Null = disconnected.
+ * @param {() => number} [options.now] Unix seconds.
+ * @returns {object}
+ */
+export function createLocalPolicyEnforcement({
+  signingKey = null,
+  now = () => Math.floor(Date.now() / 1000),
+} = {}) {
+  let active = null;
+  let lastGood = null;
+  const revoked = new Map();
+
+  function canSeal() {
+    return typeof signingKey === "string" && signingKey.length > 0;
+  }
+
+  function isRevoked(digest) {
+    return revoked.has(digest);
+  }
+
+  function mint(deniedOperations = [], ttl = DEFAULT_BUNDLE_TTL) {
+    if (!canSeal()) return null;
+    const issued = now();
+    const unique = [...new Set((Array.isArray(deniedOperations) ? deniedOperations : [])
+      .map(String))];
+    const claims = {
+      denials: { operations: unique },
+      expires: issued + (ttl ?? DEFAULT_BUNDLE_TTL),
+      id: randomUUID(),
+      issued,
+      v: POLICY_BUNDLE_VERSION,
+    };
+    const digest = digestOf(claims);
+    const seal = SEAL_PREFIX + createHmac("sha256", signingKey).update(digest).digest("hex");
+    return bundleFrom(claims, digest, seal);
+  }
+
+  function verify(document) {
+    if (!canSeal()) return null;
+    if (!document || typeof document !== "object" || Array.isArray(document)) return null;
+    const bag = new Map(Object.entries(document));
+    const seal = bag.get("seal");
+    const claimedDigest = bag.get("digest");
+    bag.delete("seal");
+    bag.delete("digest");
+    const claims = Object.fromEntries(bag);
+    if (typeof seal !== "string" || !seal.startsWith(SEAL_PREFIX)) return null;
+    if (Number(new Map(Object.entries(claims)).get("v") ?? 0) !== POLICY_BUNDLE_VERSION) {
+      return null;
+    }
+    const digest = digestOf(claims);
+    if (!safeEqual(digest, typeof claimedDigest === "string" ? claimedDigest : "")) return null;
+    const expected = SEAL_PREFIX
+      + createHmac("sha256", signingKey).update(digest).digest("hex");
+    if (!safeEqual(expected, seal)) return null;
+    const bundle = bundleFrom(claims, digest, seal);
+    if (bundle.isExpired(now())) return null;
+    if (isRevoked(digest)) return null;
+    return bundle;
+  }
+
+  function attestation() {
+    return active;
+  }
+
+  function activeDigest() {
+    const digest = active && typeof active.digest === "string" ? active.digest : null;
+    return digest || null;
+  }
+
+  function emergencyDeny() {
+    if (active && typeof active.digest === "string") lastGood = active;
+    active = {
+      digest: EMERGENCY_DIGEST,
+      activated_at: now(),
+      previous: active && typeof active.digest === "string" ? active.digest : null,
+      emergency: true,
+      bundle: {
+        v: POLICY_BUNDLE_VERSION,
+        denials: { operations: [EMERGENCY_DENY] },
+        expires: 0,
+        id: EMERGENCY_DIGEST,
+        issued: now(),
+      },
+    };
+  }
+
+  function activateBundle(bundle) {
+    if (!canSeal() || !bundle) return null;
+    if (active && typeof active.digest === "string") lastGood = active;
+    const previous = active && typeof active.digest === "string" ? active.digest : null;
+    active = {
+      digest: bundle.digest,
+      activated_at: now(),
+      previous,
+      bundle: bundle.toArray(),
+    };
+    return {
+      digest: bundle.digest,
+      activated_at: active.activated_at,
+      previous,
+    };
+  }
+
+  /**
+   * Verify then activate a portable document. This is the agent hook.
+   *
+   * @param {object} document
+   * @returns {{ok: boolean, digest?: string, attested?: boolean, reason?: string}}
+   */
+  function activate(document) {
+    const bundle = verify(document);
+    if (!bundle) return { ok: false, reason: "unverified" };
+    const result = activateBundle(bundle);
+    if (!result) return { ok: false, reason: "cannot_activate" };
+    return { ok: true, digest: result.digest, attested: true };
+  }
+
+  function simulate(operation, localDenies, candidate = null) {
+    const digest = candidate?.digest ?? activeDigest();
+    if (localDenies) {
+      return { allow: false, reason: "local_deny", digest };
+    }
+    if (candidate === null && active && active.emergency) {
+      return {
+        allow: false,
+        reason: "emergency_deny",
+        digest: digest ?? EMERGENCY_DIGEST,
+      };
+    }
+    let bundle = candidate;
+    if (bundle === null) {
+      const document = active?.bundle ?? null;
+      bundle = document ? verify(document) : null;
+      if (bundle === null && digest) {
+        return { allow: false, reason: "bundle_unverified", digest };
+      }
+    }
+    if (bundle && (bundle.denies(operation) || bundle.denies(EMERGENCY_DENY))) {
+      return { allow: false, reason: "bundle_deny", digest: bundle.digest };
+    }
+    return { allow: true, reason: "allow", digest };
+  }
+
+  function revoke(digest) {
+    if (typeof digest !== "string" || !digest) return;
+    revoked.set(digest, now());
+    if (activeDigest() === digest) emergencyDeny();
+  }
+
+  function rollback() {
+    if (!lastGood || typeof lastGood.digest !== "string") return null;
+    if (isRevoked(lastGood.digest)) return null;
+    active = lastGood;
+    return lastGood;
+  }
+
+  return {
+    canSeal,
+    mint,
+    verify,
+    activate,
+    activateBundle,
+    attestation,
+    activeDigest,
+    simulate,
+    revoke,
+    rollback,
+    emergencyDeny,
+    isRevoked,
+  };
+}

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