@mudraid/adapter-node 1.1.0

package/src/controlLoop.ts

@@ -0,0 +1,387 @@
+/**
+ * V2 enforcement control loop — the adapter-decision semantics, natively in TS.
+ *
+ * This module encodes the portable adapter-decision contract
+ * (`mudraid.adapter.decision/1`) directly, so a Node platform reaches the SAME
+ * normalized outcome as the Kong `mudraid-enforce` Lua handler, the reference
+ * runner in `shared/mudraid_contracts`, and the Python middleware — for the same
+ * facts.
+ *
+ * The decision-tree order mirrors `handler.lua:access` (and the Python
+ * `_v2_control_loop.evaluate_v2`) EXACTLY:
+ *
+ *   1. reserved `x-mudraid-*` headers are stripped FIRST, before any evaluation,
+ *      and even on requests that will be denied — trusted context is never
+ *      accepted as an input fact;
+ *   2. fail CLOSED when no verified signed bundle is active → not_safely_decided;
+ *   3. method classification — control verbs pass, non-POST denies;
+ *   4. bounded JSON-RPC framing — oversized/unreadable bodies deny, a JSON
+ *      *array* (batch) is rejected wholesale, never partially evaluated;
+ *   5. exact, case-sensitive canonical action resolution — never fuzzy/prefix;
+ *   6. a live `/decide` call, required for every protected tool invocation and
+ *      **deny-closed** on timeout/error/unconfigured;
+ *   7. allow — and only then is trusted context injected downstream.
+ *
+ * "not safely decided" (no bundle, `/decide` timeout/error) is deny-closed,
+ * never optimistically treated as allow.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import {
+  MAX_TOOL_NAME_LEN,
+  RESERVED_HEADER_PREFIX,
+  type AdapterCode,
+  type Decision,
+  type DecideClient,
+  type Outcome,
+  type ReasonTier,
+  type RequestFacts,
+  type TrustedContextHeader,
+} from './types.js';
+
+/** Streamable-HTTP control verbs — carry no JSON-RPC request, cannot invoke a tool. */
+const CONTROL_VERBS: ReadonlySet<string> = new Set(['GET', 'HEAD', 'OPTIONS', 'DELETE']);
+
+/**
+ * Control/discovery JSON-RPC methods allowed to pass a protected surface without
+ * a tool invocation (mirrors the plugin `public_methods` default). Client
+ * `notifications/*` are handled by prefix, separately.
+ */
+// Pre-launch scan SSC-05: `resources/list` and `prompts/list` used to be here
+// while the Kong plugin and the Python middleware denied them, so the same
+// client got 403 from one deployed adapter and a pass-through from another.
+// Enumeration on a protected surface is disclosure; the conservative three
+// are the contract, pinned by two corpus fixtures every runner consumes.
+const DEFAULT_PUBLIC_METHODS: ReadonlySet<string> = new Set([
+  'initialize',
+  'ping',
+  'tools/list',
+]);
+
+/**
+ * `/decide` transport-failure mode → normalized not-safely-decided reason. Every
+ * one deny-closes; the reason differs by failure mode but the surfaced adapter
+ * code is uniformly `ENFORCE_DECIDE_UNAVAILABLE`.
+ */
+const DECIDE_UNAVAILABLE_REASONS: Readonly<Record<string, string>> = {
+  timeout: 'deadline_exceeded',
+  error: 'authority_source_unavailable',
+  unreachable: 'authority_source_unavailable',
+  unconfigured: 'adapter_config_stale',
+  credential_unconfigured: 'adapter_config_stale',
+};
+
+/**
+ * Reasons that are NOT deny outcomes. A `/decide` response that tries to label a
+ * *deny* with one of these cannot leak an allow/soft outcome through the deny
+ * path; we fall back to the generic deny reason. This is a self-contained safety
+ * guard, deliberately NOT a mirror of the full governed reason-code registry
+ * (this SDK takes no dependency on the internal `mudraid_contracts` package),
+ * matching the Python middleware's guard. Extend only with reasons whose
+ * canonical outcome is provably not "deny".
+ */
+const NON_DENY_REASONS: ReadonlySet<string> = new Set([
+  'authorized', // allow
+  'adapter_config_stale', // not_safely_decided
+  'deadline_exceeded', // not_safely_decided
+  'authority_source_unavailable', // not_safely_decided
+]);
+
+const DECIDE_DENY_DEFAULT_REASON = 'policy_rule_denied';
+
+const NO_TRUSTED_CONTEXT: readonly TrustedContextHeader[] = Object.freeze([]);
+
+/**
+ * Reserved headers stripped from the request before evaluation (contract A03-04).
+ *
+ * Case-insensitive prefix match; applied on every protected request regardless
+ * of the eventual outcome (original case is preserved for auditability). On an
+ * unprotected surface the request passes through untouched, so nothing is
+ * stripped.
+ */
+export function normalizeStrippedHeaders(
+  reservedHeadersPresented: readonly string[],
+  { protectedSurface }: { readonly protectedSurface: boolean },
+): readonly string[] {
+  if (!protectedSurface) {
+    return [];
+  }
+  return reservedHeadersPresented.filter((h) =>
+    h.toLowerCase().startsWith(RESERVED_HEADER_PREFIX),
+  );
+}
+
+/** True when a header name is a reserved `x-mudraid-*` context header. */
+export function isReservedHeader(name: string): boolean {
+  return name.toLowerCase().startsWith(RESERVED_HEADER_PREFIX);
+}
+
+/** A usable canonical action name: non-empty, within the byte bound. */
+export function validToolName(name: string | null | undefined): name is string {
+  if (typeof name !== 'string') {
+    return false;
+  }
+  const byteLen = Buffer.byteLength(name, 'utf-8');
+  return byteLen > 0 && byteLen <= MAX_TOOL_NAME_LEN;
+}
+
+/** A fresh correlation id for a bound allow, forwarded as trusted context. */
+export function newDecisionId(): string {
+  return randomUUID();
+}
+
+function deny(
+  reasonCode: string,
+  tier: ReasonTier,
+  httpStatus: number,
+  adapterCode: AdapterCode,
+  message: string,
+  stripped: readonly string[],
+  outcome: Outcome = 'deny',
+): Decision {
+  return {
+    outcome,
+    reasonCode,
+    reasonTier: tier,
+    httpStatus,
+    adapterCode,
+    message,
+    strippedReservedHeaders: stripped,
+    trustedContext: NO_TRUSTED_CONTEXT,
+  };
+}
+
+function passThrough(reasonCode: string, stripped: readonly string[]): Decision {
+  return {
+    outcome: 'allow',
+    reasonCode,
+    reasonTier: 'transport',
+    httpStatus: 200,
+    adapterCode: null,
+    message: '',
+    strippedReservedHeaders: stripped,
+    trustedContext: NO_TRUSTED_CONTEXT,
+  };
+}
+
+/** Whether a decision means the request should forward to the wrapped handler. */
+export function shouldForward(decision: Decision): boolean {
+  return decision.outcome === 'allow';
+}
+
+/**
+ * Reproduce the reference control loop's outcome for one request.
+ *
+ * `decide` is invoked EXACTLY at the `/decide` branch (a mapped `tools/call` on
+ * an active bundle) and nowhere else, so a control verb, an unmapped action, or
+ * a framing rejection never triggers a live call. Any transport error thrown by
+ * the injected client is treated as `"error"` and deny-closed. Any "not safely
+ * decided" state is deny-closed, never allow.
+ */
+export async function evaluateV2(facts: RequestFacts, decide: DecideClient): Promise<Decision> {
+  const stripped = normalizeStrippedHeaders(facts.reservedHeadersPresented ?? [], {
+    protectedSurface: facts.protected,
+  });
+
+  // 1. Unprotected surface: pass through untouched (not a bundled surface).
+  if (!facts.protected) {
+    return passThrough('surface_not_protected', stripped);
+  }
+
+  // 2. Fail CLOSED: no verified signed bundle active → not_safely_decided.
+  if (!facts.bundleActive) {
+    return deny(
+      'adapter_config_stale',
+      'authorization',
+      503,
+      'ENFORCE_NO_VALID_BUNDLE',
+      'no verified signed bundle is active; request cannot be safely decided',
+      stripped,
+      'not_safely_decided',
+    );
+  }
+
+  // 3. Method classification. Control verbs pass; anything neither a control verb
+  //    nor POST is denied.
+  const method = (facts.method ?? '').toUpperCase();
+  if (CONTROL_VERBS.has(method)) {
+    return passThrough('control_plane_passthrough', stripped);
+  }
+  if (method !== 'POST') {
+    return deny(
+      'method_not_allowed',
+      'transport',
+      405,
+      'ENFORCE_METHOD_NOT_ALLOWED',
+      'method not allowed on a protected MCP surface',
+      stripped,
+    );
+  }
+
+  // 4. Bounded framing: oversized/unreadable bodies deny, never partial eval.
+  if (facts.bodyTooLarge === true) {
+    return deny(
+      'body_too_large',
+      'transport',
+      413,
+      'ENFORCE_BODY_TOO_LARGE',
+      'request body exceeds the bounded framing limit',
+      stripped,
+    );
+  }
+  if (facts.bodyReadable === false) {
+    return deny(
+      'body_unreadable',
+      'transport',
+      400,
+      'ENFORCE_BODY_UNREADABLE',
+      'request body could not be read',
+      stripped,
+    );
+  }
+
+  // 5. Parse exactly once. Non-object bodies (scalar / non-JSON) are malformed;
+  //    a JSON *array* is a batch and rejected wholesale.
+  const jsonShape = facts.jsonShape ?? 'object';
+  if (jsonShape === 'array') {
+    return deny(
+      'batch_unsupported',
+      'transport',
+      400,
+      'ENFORCE_BATCH_UNSUPPORTED',
+      'JSON-RPC batch requests are not supported',
+      stripped,
+    );
+  }
+  if (jsonShape !== 'object') {
+    return deny(
+      'malformed_request',
+      'transport',
+      400,
+      'ENFORCE_MALFORMED_REQUEST',
+      'request body is not a single JSON-RPC 2.0 object',
+      stripped,
+    );
+  }
+  const rpcMethod = facts.rpcMethod;
+  if (facts.jsonrpc !== '2.0' || typeof rpcMethod !== 'string' || rpcMethod === '') {
+    return deny(
+      'malformed_request',
+      'transport',
+      400,
+      'ENFORCE_MALFORMED_REQUEST',
+      'request body is not a single JSON-RPC 2.0 object',
+      stripped,
+    );
+  }
+
+  // 6. Non-tool protocol messages: allowlisted control/discovery + client
+  //    notifications pass; everything else on a protected surface denies rather
+  //    than slipping through because extraction found no action.
+  if (rpcMethod !== 'tools/call') {
+    if (rpcMethod.startsWith('notifications/')) {
+      return passThrough('notification_passthrough', stripped);
+    }
+    if (DEFAULT_PUBLIC_METHODS.has(rpcMethod)) {
+      return passThrough('control_plane_passthrough', stripped);
+    }
+    return deny(
+      'message_not_allowed',
+      'transport',
+      403,
+      'ENFORCE_MESSAGE_NOT_ALLOWED',
+      'JSON-RPC method is not permitted on a protected surface',
+      stripped,
+    );
+  }
+
+  // 7. Exact canonical action resolution — never fuzzy.
+  if (!validToolName(facts.toolName)) {
+    return deny(
+      'malformed_request',
+      'transport',
+      400,
+      'ENFORCE_MALFORMED_REQUEST',
+      'tools/call params.name is missing or exceeds the action-name bound',
+      stripped,
+    );
+  }
+  if (facts.actionMapped !== true) {
+    return deny(
+      'action_unmapped',
+      'authorization',
+      403,
+      'ENFORCE_ACTION_UNMAPPED',
+      'no exact canonical action is mapped for this tool',
+      stripped,
+    );
+  }
+
+  // 8. Live /decide — required for every protected call; deny-closed on
+  //    timeout/error/unconfigured. A thrown transport error is treated as
+  //    "error" (deny-closed), never optimistically allowed.
+  const action = facts.action ?? facts.toolName;
+  let result;
+  try {
+    result = await decide(action);
+  } catch {
+    // No error detail is surfaced: a transport exception may carry secrets.
+    return deny(
+      'authority_source_unavailable',
+      'authorization',
+      503,
+      'ENFORCE_DECIDE_UNAVAILABLE',
+      'the authority could not be reached; request cannot be safely decided',
+      stripped,
+      'not_safely_decided',
+    );
+  }
+
+  if (result.status === 'allow') {
+    const trusted: readonly TrustedContextHeader[] = [
+      ['x-mudraid-action-key', action],
+      ['x-mudraid-decision-id', result.decisionId ?? newDecisionId()],
+    ];
+    return {
+      outcome: 'allow',
+      reasonCode: 'authorized',
+      reasonTier: 'authorization',
+      httpStatus: 200,
+      adapterCode: null,
+      message: '',
+      strippedReservedHeaders: stripped,
+      trustedContext: trusted,
+    };
+  }
+
+  if (result.status === 'deny') {
+    let reason = result.reason ?? DECIDE_DENY_DEFAULT_REASON;
+    // A decide-supplied reason that is not provably a deny code cannot leak an
+    // allow/soft outcome through the deny path.
+    if (NON_DENY_REASONS.has(reason)) {
+      reason = DECIDE_DENY_DEFAULT_REASON;
+    }
+    return deny(
+      reason,
+      'authorization',
+      403,
+      'ENFORCE_DECISION_DENY',
+      'the authority denied this action',
+      stripped,
+    );
+  }
+
+  // timeout | error | unreachable | unconfigured | credential_unconfigured
+  // → deny-closed 503.
+  const reason = DECIDE_UNAVAILABLE_REASONS[result.status] ?? 'authority_source_unavailable';
+  return deny(
+    reason,
+    'authorization',
+    503,
+    'ENFORCE_DECIDE_UNAVAILABLE',
+    'the authority could not be reached; request cannot be safely decided',
+    stripped,
+    'not_safely_decided',
+  );
+}

package/src/decideClient.ts

@@ -0,0 +1,25 @@
+/**
+ * `/decide` seam helpers.
+ *
+ * The REAL HTTP `/decide` client (authenticated call to the MudraID authority,
+ * with timeout/retry) is a DEFERRED remainder of EP-120-US-05. This module
+ * provides only the injectable seam and in-memory fakes, so the control loop can
+ * be exercised — and proven deny-closed — with no network.
+ */
+
+import type { DecideClient, DecideResult } from './types.js';
+
+/** A seam that always returns the same fixed `/decide` result. */
+export function staticDecideClient(result: DecideResult): DecideClient {
+  return async () => result;
+}
+
+/**
+ * A seam that rejects (simulating a transport exception). The control loop
+ * catches this and deny-closes as `ENFORCE_DECIDE_UNAVAILABLE`.
+ */
+export function throwingDecideClient(error?: unknown): DecideClient {
+  return async () => {
+    throw error ?? new Error('decide transport failure');
+  };
+}

package/src/executionBinding.ts

@@ -0,0 +1,43 @@
+/** Exact request binding; supplied business values are not independent facts. */
+import {createHash} from 'node:crypto';
+import {canonicalJson, type JsonObject, type VerifiedBundle} from './signedBundle.js';
+
+export interface ExecutionContext {
+  readonly presentedAuthorization: string;
+  readonly httpMethod: string;
+  readonly path: string;
+  readonly contentType: string;
+  readonly body: Uint8Array;
+}
+
+export const sha256 = (bytes: string | Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+
+export function bindExecution(snapshot: VerifiedBundle, action: Readonly<JsonObject>, context: ExecutionContext): {digest: string; execution: JsonObject} {
+  if (!(context.body instanceof Uint8Array) || context.body.byteLength > 8 * 1024 * 1024) throw new Error('Invalid request body');
+  if (!context.contentType || context.contentType.length > 256 || /[\r\n]/.test(context.contentType)) throw new Error('Invalid content type');
+  let token = context.presentedAuthorization.trim();
+  if (token.toLowerCase().startsWith('bearer ')) token = token.slice(7).trim();
+  if (!token) throw new Error('Missing caller');
+  const scopes = action['required_scopes'];
+  if (!Array.isArray(scopes) || scopes.some(scope => typeof scope !== 'string' || !/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(scope))) throw new Error('Invalid action scopes');
+  const material: JsonObject = {
+    profile: 'mudraid.execution.request/1', body_sha256: sha256(context.body),
+    content_type: context.contentType, http_method: context.httpMethod, path: context.path,
+    caller_token_sha256: sha256(token), platform_id: snapshot.surface['platform_id'],
+    environment: snapshot.surface['environment'], resource: snapshot.surface['canonical_resource_uri'],
+    action_key: action['action_key'], action_version: action['action_version'],
+    mapping_id: action['mapping_id'], mapping_version: action['mapping_revision'],
+    bundle_version: snapshot.version, bundle_payload_digest: snapshot.digest,
+    required_scopes: [...new Set(scopes)].sort(),
+  };
+  if (Object.values(material).some(value => value === undefined || value === null || value === '')) throw new Error('Incomplete execution binding');
+  return {digest: sha256(canonicalJson(material)), execution: {
+    profile: material['profile'], body_sha256: material['body_sha256'], content_type: material['content_type'],
+    ...(action['argument_profile'] == null ? {} : {body_base64: boundedArgumentBody(context.body)}),
+  }};
+}
+
+function boundedArgumentBody(body: Uint8Array): string {
+  if (body.byteLength === 0 || body.byteLength > 65536) throw new Error('Argument body exceeds bounds');
+  return Buffer.from(body).toString('base64');
+}

package/src/httpAuthority.ts

@@ -0,0 +1,185 @@
+/** Authenticated, bounded authority transport. No decision or upstream retries. */
+import { randomUUID } from 'node:crypto';
+import { instant, object, verifyBundle, verifyClaims, type BundleBinding, type JsonObject, type VerifiedBundle } from './signedBundle.js';
+import type { DecideResult } from './types.js';
+
+import {bindExecution, type ExecutionContext} from './executionBinding.js';
+export type InvocationContext = ExecutionContext;
+export interface AuthorityOptions {
+  readonly apiBase: string;
+  readonly adapterToken: string;
+  readonly binding: BundleBinding;
+  readonly timeoutMs?: number;
+  readonly adapterType?: 'node_server_adapter' | 'node_sidecar';
+  readonly fetch?: typeof fetch;
+}
+
+function keyMap(entries: unknown): Record<string, string> {
+  if (!Array.isArray(entries)) throw new Error('Invalid verification key set');
+  const keys: Record<string, string> = Object.create(null);
+  for (const entry of entries) {
+    const row = object(entry);
+    if (typeof row['key_id'] !== 'string' || typeof row['public_key_pem'] !== 'string' || Object.hasOwn(keys, row['key_id'])) throw new Error('Invalid verification key');
+    keys[row['key_id']] = row['public_key_pem'];
+  }
+  return keys;
+}
+
+export class HttpAuthority {
+  private readonly base: URL;
+  private readonly token: string;
+  private readonly binding: BundleBinding;
+  private readonly timeout: number;
+  private readonly adapterType: 'node_server_adapter' | 'node_sidecar';
+  private readonly fetcher: typeof fetch;
+  private current: VerifiedBundle | undefined;
+  private lastAccepted: VerifiedBundle | undefined;
+  private decisionKeys: Record<string, string> = Object.create(null);
+  private refreshPending: Promise<boolean> | undefined;
+  private observed: {version: number; digest: string; at: string} | undefined;
+
+  constructor(options: AuthorityOptions) {
+    this.base = new URL(options.apiBase);
+    if (this.base.protocol !== 'https:' || this.base.username || this.base.password || this.base.search || this.base.hash || this.base.pathname !== '/') throw new Error('Authority must be an HTTPS origin');
+    if (!options.adapterToken || options.adapterToken.length > 256 || /\s/.test(options.adapterToken)) throw new Error('Invalid adapter credential');
+    this.token = options.adapterToken;
+    this.adapterType = options.adapterType ?? 'node_server_adapter';
+    this.binding = Object.freeze({...options.binding});
+    this.timeout = options.timeoutMs ?? 5000;
+    if (!Number.isSafeInteger(this.timeout) || this.timeout < 1 || this.timeout > 30000) throw new Error('Invalid authority timeout');
+    this.fetcher = options.fetch ?? globalThis.fetch;
+  }
+
+  get bundle(): VerifiedBundle | undefined {
+    return this.current && this.current.expiresAt > Date.now() ? this.current : undefined;
+  }
+
+  private async request(path: string, method: string, body?: unknown, authenticated = true): Promise<JsonObject> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await this.fetcher(new URL(`/api/v1/adapter/enforcement/${path}`, this.base), {
+        method, redirect: 'error', signal: controller.signal,
+        headers: {Accept: 'application/json', ...(authenticated ? {Authorization: `Bearer ${this.token}`} : {}), ...(body === undefined ? {} : {'Content-Type': 'application/json'})},
+        ...(body === undefined ? {} : {body: JSON.stringify(body)}),
+      });
+      if (!response.ok || !response.body) throw new Error('Authority unavailable');
+      const reader = response.body.getReader();
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      try {
+        while (true) {
+          const item = await reader.read();
+          if (item.done) break;
+          size += item.value.byteLength;
+          if (size > 2 * 1024 * 1024) throw new Error('Authority response too large');
+          chunks.push(item.value);
+        }
+      } finally {
+        await reader.cancel();
+      }
+      return object(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Single-flight refresh. A failed refresh never activates unverified data. */
+  refresh(): Promise<boolean> {
+    if (!this.refreshPending) this.refreshPending = this.refreshOnce().finally(() => { this.refreshPending = undefined; });
+    return this.refreshPending;
+  }
+
+  private async refreshOnce(): Promise<boolean> {
+    try {
+      const heartbeat = await this.request('heartbeat', 'POST');
+      if (heartbeat['platform_id'] !== this.binding.platformId) {
+        this.current = undefined;
+        return false;
+      }
+      const keyResponse = await this.request('keys', 'GET', undefined, false);
+      const bundleKeys = keyMap(keyResponse['keys']);
+      this.decisionKeys = Object.create(null);
+      if (Array.isArray(keyResponse['key_sets'])) {
+        for (const item of keyResponse['key_sets']) {
+          const set = object(item);
+          if (set['purpose'] === 'enforcement_decision_signing') this.decisionKeys = keyMap(set['keys']);
+        }
+      }
+      const served = await this.request('bundle', 'GET');
+      const verified = verifyBundle(served, bundleKeys, this.binding, this.lastAccepted);
+      // Heartbeat attribution is authoritative; a stale advertised bundle is not active.
+      if (heartbeat['desired_bundle_version'] !== verified.version || heartbeat['desired_payload_digest'] !== verified.digest) throw new Error('Desired bundle mismatch');
+      this.current = verified;
+      this.lastAccepted = verified;
+      const now = new Date().toISOString();
+      const observedAt = this.observed?.version === verified.version && this.observed.digest === verified.digest
+        ? this.observed.at : undefined;
+      await this.request('acknowledgements', 'POST', {
+        report_id: randomUUID(), received_version: verified.version, received_at: now,
+        validated_version: verified.version, validated_at: now, active_version: verified.version,
+        active_at: now, bundle_digest: verified.digest,
+        ...(observedAt === undefined ? {} : {first_observed_decision_at: observedAt}),
+      });
+      return true;
+    } catch {
+      // Fail closed until the next verified refresh; do not hide key revocation
+      // behind a cached bundle after an authoritative key-set replacement.
+      this.current = undefined;
+      return false;
+    }
+  }
+
+  async decide(toolName: string, context: InvocationContext, snapshot = this.bundle): Promise<DecideResult> {
+    if (!snapshot || snapshot !== this.bundle) return {status: 'unconfigured'};
+    const mapped = snapshot.actions[toolName];
+    if (!mapped) return {status: 'deny', reason: 'action_unmapped'};
+    if (!context.presentedAuthorization || context.presentedAuthorization.length > 8192) return {status: 'deny', reason: 'credential_missing'};
+    const decisionId = randomUUID();
+    const action = mapped['action_key'];
+    try {
+      const bound = bindExecution(snapshot, mapped, context);
+      const response = await this.request('decide', 'POST', {
+        schema_version: 'mudraid.enforce.decide-request/1', decision_id: decisionId,
+        adapter: {type: this.adapterType, version: '1.1.0'},
+        bundle: {version: snapshot.version, payload_digest: snapshot.digest},
+        surface: snapshot.surface, action: mapped,
+        request: {transport: 'mcp_streamable_http', http_method: context.httpMethod, path: context.path},
+        presented_authorization: context.presentedAuthorization, execution: bound.execution,
+      });
+      if (response['schema_version'] !== '2.0' || response['decision_id'] !== decisionId) throw new Error('Unbound decision');
+      const now = Date.now();
+      const decidedAt = instant(response['decided_at']);
+      if (decidedAt > now + 30000 || now - decidedAt > 60000) throw new Error('Stale decision');
+      if (instant(response['deadline_at']) <= now) throw new Error('Expired decision');
+      // This new runtime always requires signed decisions; there is no downgrade toggle.
+      const signature = object(response['signature']);
+      const claims = object(signature['claims']);
+      const keyId = signature['key_id'];
+      const profile = 'mudraid.decision.signature/1';
+      if (typeof keyId !== 'string' || !Object.hasOwn(this.decisionKeys, keyId) || signature['profile'] !== profile || signature['algorithm'] !== 'RS256' || claims['profile'] !== profile || claims['algorithm'] !== 'RS256' || claims['key_id'] !== keyId) throw new Error('Invalid decision signature');
+      verifyClaims(claims, signature['signature'], this.decisionKeys[keyId]);
+      if (claims['execution_request_digest'] !== bound.digest) throw new Error('Execution binding mismatch');
+      for (const field of ['decision_id', 'decision', 'outcome', 'decided_at', 'deadline_at']) {
+        if ((claims[field] ?? null) !== (response[field] ?? null)) throw new Error('Altered decision');
+      }
+      const reason = object(response['reason']);
+      if (claims['reason_primary'] !== reason['primary']) throw new Error('Altered reason');
+      for (const [field, expected] of Object.entries({platform_id: this.binding.platformId, environment: this.binding.environment, resource: this.binding.resource, action_key: action, bundle_version: snapshot.version})) {
+        if (claims[field] !== expected) throw new Error('Decision binding mismatch');
+      }
+      if (instant(claims['not_before']) > now + 30000 || instant(claims['expires_at']) <= now) throw new Error('Invalid decision window');
+      if (snapshot !== this.bundle) throw new Error('Bundle changed during decision');
+      if (response['decision'] !== 'allow' && response['decision'] !== 'deny') throw new Error('Invalid decision outcome');
+      // Observation is a verified decision, not proof that the application
+      // executed it. Report on the next refresh without delaying execution or
+      // replaying a decision. Keep at most one bundle's observation in memory.
+      if (this.observed?.version !== snapshot.version || this.observed.digest !== snapshot.digest) {
+        this.observed = {version: snapshot.version, digest: snapshot.digest, at: new Date(now).toISOString()};
+      }
+      return {status: response['decision'], decisionId, ...(typeof reason['primary'] === 'string' ? {reason: reason['primary']} : {})};
+    } catch {
+      return {status: 'error'};
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * `@mudraid/adapter-node` — framework-neutral TypeScript/Node server adapter for
+ * MudraID enforcement (EP-120-US-05, first slice).
+ *
+ * Public surface: the typed decision vocabulary, the V2 control loop, and the
+ * injectable `/decide` seam. The framework hooks (Express/Fastify/MCP), the real
+ * HTTP `/decide` client, and live fact extraction are DEFERRED remainders.
+ */
+
+export {
+  ADAPTER_DECISION_CONTRACT_VERSION,
+  MAX_TOOL_NAME_LEN,
+  RESERVED_HEADER_PREFIX,
+  type AdapterCode,
+  type Decision,
+  type DecideClient,
+  type DecideResult,
+  type DecideStatus,
+  type JsonShape,
+  type Outcome,
+  type ReasonTier,
+  type RequestFacts,
+  type TrustedContextHeader,
+} from './types.js';
+
+export {
+  evaluateV2,
+  isReservedHeader,
+  newDecisionId,
+  normalizeStrippedHeaders,
+  shouldForward,
+  validToolName,
+} from './controlLoop.js';
+
+export { staticDecideClient, throwingDecideClient } from './decideClient.js';
+
+export { verifyBundle, type BundleBinding, type VerifiedBundle } from './signedBundle.js';
+export { HttpAuthority, type AuthorityOptions, type InvocationContext } from './httpAuthority.js';