@emilia-protocol/gate 0.18.1 → 0.19.0

package/src/gate-qualification-v2.ts

@@ -6,6 +6,7 @@
  * immutable AdmissionSnapshot may cross the one-time invocation boundary.
  */
 
+import crypto from 'node:crypto';
 import { createAdmissionSnapshot } from './admission-store.js';
 import type {
   AdmissionSnapshot,
@@ -30,6 +31,14 @@ const REQUIRED_QUALIFICATION_CHECKS = Object.freeze([
   'assignment_in_scope',
   'protected_request_bound',
 ] as const);
+const GATE_QUALIFICATION_V2_PROGRAM_DIGEST = `sha256:${crypto
+  .createHash('sha256')
+  .update(JSON.stringify({
+    version: GATE_QUALIFICATION_V2_VERSION,
+    checks: REQUIRED_QUALIFICATION_CHECKS,
+    requirements: ['qualification', 'aeb', 'aec', 'local_policy'],
+  }))
+  .digest('hex')}` as const;
 const DEFAULT_ADAPTER_TIMEOUT_MS = 30_000;
 const MAX_ADAPTER_TIMEOUT_MS = 300_000;
 
@@ -56,6 +65,8 @@ export interface BoundRequirementDecisionV2 {
 export interface BoundLocalPolicyDecisionV2 {
   readonly decision: 'allow' | 'deny';
   readonly policyId: string;
+  /** Digest of the relying-party authorization policy that made this decision. */
+  readonly policyDigest?: AdmissionDigestV2;
   readonly caid: string;
   readonly actionDigest: AdmissionDigestV2;
   readonly evidenceDigest: AdmissionDigestV2;
@@ -85,6 +96,7 @@ export interface GateQualificationDecisionV2 {
   readonly caid: string;
   readonly actionDigest: string;
   readonly snapshotDigest: string;
+  readonly programDigest: AdmissionDigestV2;
   readonly effectKey: string;
   readonly requirements: Readonly<{
     qualificationEvidenceDigest: string;
@@ -222,6 +234,7 @@ export type GateQualificationExecutionResultV2 =
   | {
       readonly status: 'refused';
       readonly reason: string;
+      readonly programDigest: AdmissionDigestV2;
       readonly decision?: Readonly<GateQualificationDecisionV2>;
     }
   | {
@@ -505,6 +518,11 @@ function validateLocalPolicy(
   if (!validString(leg.policyId)) {
     addReason(reasons, 'localPolicy_policy_missing');
   }
+  if (!validDigest(leg.policyDigest)) {
+    addReason(reasons, 'localPolicy_program_digest_missing');
+  } else if (leg.policyDigest !== snapshot.body.authorization_policy_digest) {
+    addReason(reasons, 'localPolicy_program_digest_mismatch');
+  }
   if (leg.caid !== snapshot.body.caid
       || leg.actionDigest !== snapshot.body.action_digest) {
     addReason(reasons, 'localPolicy_binding_mismatch');
@@ -580,6 +598,7 @@ function emptyDecision(reasons: readonly string[]): GateQualificationDecisionV2
     caid: '',
     actionDigest: '',
     snapshotDigest: '',
+    programDigest: GATE_QUALIFICATION_V2_PROGRAM_DIGEST,
     effectKey: '',
     requirements: deepFreeze({
       qualificationEvidenceDigest: '',
@@ -613,6 +632,7 @@ function composeCanonical(
     caid: snapshot.body.caid,
     actionDigest: snapshot.body.action_digest,
     snapshotDigest: snapshot.snapshot_digest,
+    programDigest: snapshot.body.authorization_policy_digest,
     effectKey: actuationKey(snapshot),
     requirements: deepFreeze({
       qualificationEvidenceDigest:
@@ -785,6 +805,20 @@ function reconciliationRequired(
   return deepFreeze({ status: 'reconciliation_required', reason, admissionId });
 }
 
+function refused(
+  reason: string,
+  decision?: Readonly<GateQualificationDecisionV2>,
+  programDigest: AdmissionDigestV2 = decision?.programDigest
+    ?? GATE_QUALIFICATION_V2_PROGRAM_DIGEST,
+): Readonly<GateQualificationExecutionResultV2> {
+  return deepFreeze({
+    status: 'refused',
+    reason,
+    programDigest,
+    ...(decision ? { decision } : {}),
+  });
+}
+
 export class GateQualificationV2 {
   readonly mode: QualificationModeV2;
   readonly #store?: AdmissionStore;
@@ -1022,7 +1056,7 @@ export class GateQualificationV2 {
     decision: Readonly<GateQualificationDecisionV2>,
   ): Promise<GateQualificationExecutionResultV2> {
     if (storeReason !== 'admission_exists') {
-      return deepFreeze({ status: 'refused', reason: storeReason, decision });
+      return refused(storeReason, decision);
     }
     try {
       const record = await this.#store!.read(reference(snapshot));
@@ -1037,7 +1071,7 @@ export class GateQualificationV2 {
         'admission_read_ambiguous',
       );
     }
-    return deepFreeze({ status: 'refused', reason: storeReason, decision });
+    return refused(storeReason, decision);
   }
 
   async #verifyProviderEvidence(
@@ -1228,11 +1262,10 @@ export class GateQualificationV2 {
       : emptyDecision(['admission_snapshot_invalid']);
     if (this.mode === 'shadow') return this.#shadow(input, decision);
     if (!checked.ok || !decision.allow) {
-      return deepFreeze({
-        status: 'refused',
-        reason: decision.reasons[0] ?? 'qualification_refused',
+      return refused(
+        decision.reasons[0] ?? 'qualification_refused',
         decision,
-      });
+      );
     }
 
     const snapshot = checked.snapshot;
@@ -1240,11 +1273,7 @@ export class GateQualificationV2 {
     try {
       reserved = await this.#store!.reserve(snapshot);
     } catch {
-      return deepFreeze({
-        status: 'refused',
-        reason: 'admission_reserve_failed',
-        decision,
-      });
+      return refused('admission_reserve_failed', decision);
     }
     if (!reserved.ok) {
       return this.#existingAdmissionResult(snapshot, reserved.reason, decision);
@@ -1263,11 +1292,7 @@ export class GateQualificationV2 {
       } catch {
         // No provider entry occurred; the reservation remains closed.
       }
-      return deepFreeze({
-        status: 'refused',
-        reason: 'reserve_snapshot_mismatch',
-        decision,
-      });
+      return refused('reserve_snapshot_mismatch', decision);
     }
 
     // Reread the candidate, qualification status, AEB, AEC, local policy and
@@ -1290,11 +1315,7 @@ export class GateQualificationV2 {
       } catch {
         // No execution right was consumed and no provider entry occurred.
       }
-      return deepFreeze({
-        status: 'refused',
-        reason: 'invocation_remeasurement_failed',
-        decision,
-      });
+      return refused('invocation_remeasurement_failed', decision);
     }
     const refreshedDecision = composeCanonical(
       reserved.snapshot,
@@ -1310,12 +1331,10 @@ export class GateQualificationV2 {
       } catch {
         // No execution right was consumed and no provider entry occurred.
       }
-      return deepFreeze({
-        status: 'refused',
-        reason: refreshedDecision.reasons[0]
-          ?? 'invocation_remeasurement_refused',
-        decision: refreshedDecision,
-      });
+      return refused(
+        refreshedDecision.reasons[0] ?? 'invocation_remeasurement_refused',
+        refreshedDecision,
+      );
     }
 
     let begun: Awaited<ReturnType<AdmissionStore['beginInvocation']>>;
@@ -1333,11 +1352,7 @@ export class GateQualificationV2 {
           || begun.reason === 'revision_conflict') {
         return this.#beginAmbiguity(reserved.snapshot, reserved.owner_token);
       }
-      return deepFreeze({
-        status: 'refused',
-        reason: begun.reason,
-        decision,
-      });
+      return refused(begun.reason, decision);
     }
 
     const begunSnapshot = canonicalSnapshot(begun.snapshot);
@@ -1404,14 +1419,11 @@ export class GateQualificationV2 {
     >>,
   ): Promise<GateQualificationExecutionResultV2> {
     if (this.mode !== 'enforce') {
-      return deepFreeze({
-        status: 'refused',
-        reason: 'reconciliation_unavailable_in_shadow',
-      });
+      return refused('reconciliation_unavailable_in_shadow');
     }
     if (!input || !validString(input.tenant_id)
         || !validString(input.admission_id)) {
-      return deepFreeze({ status: 'refused', reason: 'admission_reference_invalid' });
+      return refused('admission_reference_invalid');
     }
 
     let record: StoreRecordV2 | null;
@@ -1424,13 +1436,10 @@ export class GateQualificationV2 {
       );
     }
     if (!record) {
-      return deepFreeze({ status: 'refused', reason: 'admission_not_found' });
+      return refused('admission_not_found');
     }
     if (record.execution_right !== 'CONSUMED') {
-      return deepFreeze({
-        status: 'refused',
-        reason: 'reconciliation_not_required',
-      });
+      return refused('reconciliation_not_required');
     }
 
     let snapshot: Readonly<AdmissionSnapshot> | null;
@@ -1499,10 +1508,11 @@ export class GateQualificationV2 {
     const effectUnresolved = !record.effect_relation
       || record.effect_relation.value === 'INDETERMINATE';
     if (!providerUnresolved && !effectUnresolved) {
-      return deepFreeze({
-        status: 'refused',
-        reason: 'reconciliation_not_required',
-      });
+      return refused(
+        'reconciliation_not_required',
+        undefined,
+        snapshot.body.authorization_policy_digest,
+      );
     }
 
     const base = protectedInvocation(snapshot, authority.invocationToken);

package/src/index.ts

@@ -236,6 +236,8 @@ export * from './autonomy-control-plane-profile.js';
 export * from './admission-store.js';
 export * from './admission-store-postgres.js';
 export * from './gate-qualification-v2.js';
+export * from './referee.js';
+export * from './referee-runner.js';
 export {
   ZK_RANGE_RECEIPT_VERSION,
   ZK_RANGE_SCHEME,

package/src/referee-runner.ts

@@ -0,0 +1,365 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Bounded subprocess transport for EMILIA protocol Referee runners.
+ *
+ * The caller pins an absolute executable, its SHA-256 byte digest, and the
+ * complete argument vector.  The child receives only a closed JSON request on
+ * stdin and must return one closed JSON output on stdout.  This is a bounded,
+ * no-shell subprocess self-test harness; it is not an OS sandbox and does not
+ * claim to confine a hostile executable's filesystem or network access.
+ */
+
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+
+import {
+  REFEREE_EVALUATION_VERSION,
+  RefereeValidationError,
+  createIndeterminateRefereeResult,
+  evaluateReferee,
+  parseRefereeRunnerOutput,
+  parseRefereeRunnerPin,
+  parseRefereeRunnerRequest,
+  type RefereeResultV1,
+  type RefereeRunnerOutputV1,
+  type RefereeRunnerPinV1,
+  type RefereeRunnerRequestV1,
+} from './referee.js';
+import { strictJsonGate } from './strict-json.js';
+
+export const REFEREE_RUNNER_MAX_INPUT_BYTES = 8 * 1024 * 1024;
+export const REFEREE_RUNNER_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+export const REFEREE_RUNNER_MAX_TIMEOUT_MS = 300_000;
+
+const FORCE_KILL_AFTER_MS = 100;
+const INVOCATION_KEYS = Object.freeze([
+  'runner_pin', 'request', 'timeout_ms',
+] as const);
+const OPTION_KEYS = new Set(['signal']);
+
+export type RefereeRunnerFailureCode =
+  | 'ABORTED'
+  | 'INPUT_TOO_LARGE'
+  | 'OUTPUT_TOO_LARGE'
+  | 'TIMEOUT'
+  | 'EXECUTABLE_DIGEST_MISMATCH'
+  | 'SPAWN_FAILED'
+  | 'NONZERO_EXIT'
+  | 'MALFORMED_OUTPUT'
+  | 'INVALID_OUTPUT_SCHEMA';
+
+export interface RefereeRunnerInvocationV1 {
+  readonly runner_pin: RefereeRunnerPinV1;
+  readonly request: RefereeRunnerRequestV1;
+  readonly timeout_ms: number;
+}
+
+export interface RefereeRunnerOptions {
+  readonly signal?: AbortSignal;
+}
+
+export type RefereeRunnerExecutionResult =
+  | Readonly<{
+      ok: true;
+      output: Readonly<RefereeRunnerOutputV1>;
+    }>
+  | Readonly<{
+      ok: false;
+      code: RefereeRunnerFailureCode;
+    }>;
+
+function fail(code: string): never {
+  throw new RefereeValidationError(code);
+}
+
+function plain(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function exactInvocation(value: unknown): Record<(typeof INVOCATION_KEYS)[number], unknown> {
+  if (!plain(value)) fail('invalid_schema');
+  const ownKeys = Reflect.ownKeys(value);
+  if (ownKeys.some((key) => typeof key !== 'string')) fail('unknown_key');
+  const expected = new Set<string>(INVOCATION_KEYS);
+  for (const key of ownKeys as string[]) {
+    if (!expected.has(key)) fail('unknown_key');
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable || !('value' in descriptor)) fail('invalid_schema');
+  }
+  for (const key of INVOCATION_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) fail('missing_key');
+  }
+  return value as Record<(typeof INVOCATION_KEYS)[number], unknown>;
+}
+
+function parseOptions(value: unknown): Readonly<RefereeRunnerOptions> {
+  if (value === undefined) return Object.freeze({});
+  if (!plain(value)) fail('invalid_options');
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string' || !OPTION_KEYS.has(key))) {
+    fail('unknown_key');
+  }
+  let signal: unknown;
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      fail('invalid_options');
+    }
+    if (key === 'signal') signal = descriptor.value;
+  }
+  if (signal !== undefined && !(signal instanceof AbortSignal)) {
+    fail('invalid_signal');
+  }
+  return Object.freeze(signal === undefined ? {} : { signal });
+}
+
+export function parseRefereeRunnerInvocation(
+  value: unknown,
+): Readonly<RefereeRunnerInvocationV1> {
+  const object = exactInvocation(value);
+  if (!Number.isSafeInteger(object.timeout_ms)
+    || (object.timeout_ms as number) < 1
+    || (object.timeout_ms as number) > REFEREE_RUNNER_MAX_TIMEOUT_MS) {
+    fail('invalid_timeout');
+  }
+  return Object.freeze({
+    runner_pin: parseRefereeRunnerPin(object.runner_pin),
+    request: parseRefereeRunnerRequest(object.request),
+    timeout_ms: object.timeout_ms as number,
+  });
+}
+
+function frozenFailure(code: RefereeRunnerFailureCode): RefereeRunnerExecutionResult {
+  return Object.freeze({ ok: false as const, code });
+}
+
+function frozenSuccess(
+  output: Readonly<RefereeRunnerOutputV1>,
+): RefereeRunnerExecutionResult {
+  return Object.freeze({ ok: true as const, output });
+}
+
+function decodeRunnerOutput(bytes: Buffer): RefereeRunnerExecutionResult {
+  let raw: string;
+  try {
+    raw = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return frozenFailure('MALFORMED_OUTPUT');
+  }
+  const gate = strictJsonGate(raw);
+  if (!gate.ok) return frozenFailure('MALFORMED_OUTPUT');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return frozenFailure('MALFORMED_OUTPUT');
+  }
+  try {
+    return frozenSuccess(parseRefereeRunnerOutput(parsed));
+  } catch (error) {
+    if (error instanceof RefereeValidationError) {
+      return frozenFailure('INVALID_OUTPUT_SCHEMA');
+    }
+    return frozenFailure('INVALID_OUTPUT_SCHEMA');
+  }
+}
+
+function serializeRequest(
+  request: Readonly<RefereeRunnerRequestV1>,
+): string {
+  // parseRefereeRunnerRequest has already established an exact JSON tree, so
+  // JSON.stringify cannot silently drop or coerce any member here.
+  return JSON.stringify(request);
+}
+
+async function digestExecutable(
+  executable: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  return new Promise((resolve) => {
+    const hash = crypto.createHash('sha256');
+    const stream = createReadStream(executable, { signal });
+    let complete = false;
+    const finish = (value: string | null) => {
+      if (complete) return;
+      complete = true;
+      resolve(value);
+    };
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.once('error', () => finish(null));
+    stream.once('end', () => finish(`sha256:${hash.digest('hex')}`));
+  });
+}
+
+async function executeParsed(
+  invocation: Readonly<RefereeRunnerInvocationV1>,
+  options: Readonly<RefereeRunnerOptions>,
+): Promise<RefereeRunnerExecutionResult> {
+  const serialized = serializeRequest(invocation.request);
+  if (Buffer.byteLength(serialized, 'utf8') > REFEREE_RUNNER_MAX_INPUT_BYTES) {
+    return frozenFailure('INPUT_TOO_LARGE');
+  }
+  if (options.signal?.aborted) return frozenFailure('ABORTED');
+
+  // This is intentionally the last asynchronous operation before spawn.  It
+  // establishes byte equality with the relying party's pin; it does not turn
+  // this portable harness into a complete OS-level execution sandbox.
+  const observedExecutableDigest = await digestExecutable(
+    invocation.runner_pin.executable,
+    options.signal,
+  );
+  if (options.signal?.aborted) return frozenFailure('ABORTED');
+  if (observedExecutableDigest === null) return frozenFailure('SPAWN_FAILED');
+  if (observedExecutableDigest !== invocation.runner_pin.executable_sha256) {
+    return frozenFailure('EXECUTABLE_DIGEST_MISMATCH');
+  }
+
+  return new Promise<RefereeRunnerExecutionResult>((resolve) => {
+    const detached = process.platform !== 'win32';
+    let child;
+    try {
+      child = spawn(invocation.runner_pin.executable, [...invocation.runner_pin.args], {
+        cwd: path.parse(invocation.runner_pin.executable).root,
+        detached,
+        env: {},
+        shell: false,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+    } catch {
+      resolve(frozenFailure('SPAWN_FAILED'));
+      return;
+    }
+
+    let settled = false;
+    let selectedFailure: RefereeRunnerFailureCode | null = null;
+    let totalOutputBytes = 0;
+    let stdoutBytes = 0;
+    const stdoutChunks: Buffer[] = [];
+    let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const sendSignal = (signal: NodeJS.Signals) => {
+      if (child.pid !== undefined && detached) {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch {
+          // The process may have exited between the event and this signal.
+        }
+      }
+      try {
+        child.kill(signal);
+      } catch {
+        // close/error remains the authoritative completion event.
+      }
+    };
+
+    const timeout = setTimeout(() => {
+      terminate('TIMEOUT');
+    }, invocation.timeout_ms);
+    timeout.unref?.();
+
+    const abort = () => terminate('ABORTED');
+    options.signal?.addEventListener('abort', abort, { once: true });
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer !== null) clearTimeout(forceKillTimer);
+      options.signal?.removeEventListener('abort', abort);
+    };
+
+    const finish = (result: RefereeRunnerExecutionResult) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    function terminate(code: RefereeRunnerFailureCode) {
+      if (settled || selectedFailure !== null) return;
+      selectedFailure = code;
+      sendSignal('SIGTERM');
+      forceKillTimer = setTimeout(() => sendSignal('SIGKILL'), FORCE_KILL_AFTER_MS);
+      forceKillTimer.unref?.();
+    }
+
+    const accountOutput = (chunk: Buffer | string, capture: boolean) => {
+      if (settled || selectedFailure !== null) return;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      totalOutputBytes += bytes.byteLength;
+      if (totalOutputBytes > REFEREE_RUNNER_MAX_OUTPUT_BYTES) {
+        terminate('OUTPUT_TOO_LARGE');
+        return;
+      }
+      if (capture) {
+        stdoutBytes += bytes.byteLength;
+        stdoutChunks.push(bytes);
+      }
+    };
+
+    child.stdout.on('data', (chunk: Buffer) => accountOutput(chunk, true));
+    child.stderr.on('data', (chunk: Buffer) => accountOutput(chunk, false));
+    child.stdin.on('error', () => {
+      // EPIPE is resolved by the child's close/error result, never by ambient
+      // error text or timing.
+    });
+    child.once('error', () => finish(frozenFailure(
+      selectedFailure ?? 'SPAWN_FAILED',
+    )));
+    child.once('close', (code) => {
+      if (selectedFailure !== null) {
+        finish(frozenFailure(selectedFailure));
+        return;
+      }
+      if (code !== 0) {
+        finish(frozenFailure('NONZERO_EXIT'));
+        return;
+      }
+      finish(decodeRunnerOutput(Buffer.concat(stdoutChunks, stdoutBytes)));
+    });
+
+    child.stdin.end(serialized, 'utf8');
+  });
+}
+
+/** Execute a caller-pinned protocol runner without shell or ambient config. */
+export async function runPinnedProtocolRunner(
+  value: unknown,
+  rawOptions?: unknown,
+): Promise<RefereeRunnerExecutionResult> {
+  const invocation = parseRefereeRunnerInvocation(value);
+  const options = parseOptions(rawOptions);
+  return executeParsed(invocation, options);
+}
+
+/** Execute and evaluate one self-test, mapping every runner failure to no-claim. */
+export async function runReferee(
+  value: unknown,
+  rawOptions?: unknown,
+): Promise<Readonly<RefereeResultV1>> {
+  // Snapshot every caller-controlled field before the first asynchronous edge.
+  const invocation = parseRefereeRunnerInvocation(value);
+  const options = parseOptions(rawOptions);
+  const execution = await executeParsed(invocation, options);
+  if (!execution.ok) {
+    return createIndeterminateRefereeResult({
+      runner_pin: invocation.runner_pin,
+      request: invocation.request,
+      reason_code: `runner_${execution.code.toLowerCase()}`,
+    });
+  }
+  return evaluateReferee({
+    version: REFEREE_EVALUATION_VERSION,
+    runner_pin: invocation.runner_pin,
+    request: invocation.request,
+    output: execution.output,
+  });
+}