@kontourai/flow-agents 3.8.0 → 3.10.0

package/scripts/hooks/lib/actor-identity.js

@@ -23,10 +23,8 @@
  *      passed through `sanitizeSegment` (64-char cap; strips `:`) before use
  *      — it is never returned verbatim.
  *   2. A runtime-native session-id env var already ambient in the current
- *      process's own environment (confirmed for Claude Code:
- *      `CLAUDECODE`/`CLAUDE_CODE_SESSION_ID`; Codex/opencode/pi candidate
- *      var names below are UNVERIFIED in this planning pass — accepted gap,
- *      see plan artifact — layer 3 is the correctness backstop for them).
+ *      process's own environment (including Codex's `CODEX_THREAD_ID`, with
+ *      `CODEX_SESSION_ID` retained as a backward-compatible legacy input).
  *   3. A process-ancestry fallback: `process.ppid` plus that parent
  *      process's exact start timestamp (an absolute timestamp, not an
  *      elapsed-time subtraction, to avoid clock-drift flicker across
@@ -46,7 +44,8 @@
  *   ancestorActorSeed()      → short opaque token from parent PID + start time, else ""
  *   sanitizeSegment(value)   → value restricted to [A-Za-z0-9_.-], capped 64 chars
  *   serializeActor(actor)    → actor struct serialized to a single grouping-key-safe string
- *   resolveActor(env)        → { actor: string, source: string }
+ *   resolveActorIdentity(env) → { actor: string, source: string, actorStruct: object|null }
+ *   resolveActor(env)        → backward-compatible { actor: string, source: string } projection
  *   isUnresolvedActor(actor) → boolean (true when actor is empty or the retired literal
  *                              "local", case-insensitive — single-sourced predicate shared by
  *                              the lifecycle auto-emit path, the direct CLI liveness path, and
@@ -61,13 +60,12 @@ const { execFileSync } = require('child_process');
 
 /** Candidate env var names for each runtime's native session id. */
 const RUNTIME_SESSION_ID_VARS = {
-  'claude-code': 'CLAUDE_CODE_SESSION_ID',
-  // Codex/opencode/pi candidate names are UNVERIFIED (no confirmed spike this
-  // planning pass) — accepted gap. Detection failure never blocks resolution;
-  // the process-ancestry fallback (layer 3) covers these runtimes either way.
-  codex: 'CODEX_SESSION_ID',
-  opencode: 'OPENCODE_SESSION_ID',
-  pi: 'PI_SESSION_ID',
+  'claude-code': ['CLAUDE_CODE_SESSION_ID'],
+  codex: ['CODEX_THREAD_ID', 'CODEX_SESSION_ID'],
+  // opencode/pi names remain candidate inputs. Detection failure never blocks
+  // resolution; process ancestry is the correctness backstop.
+  opencode: ['OPENCODE_SESSION_ID'],
+  pi: ['PI_SESSION_ID'],
 };
 
 /**
@@ -83,7 +81,7 @@ function detectRuntime(env = process.env) {
   if (env.CLAUDECODE === '1' || String(env.CLAUDE_CODE_SESSION_ID || '').trim()) {
     return 'claude-code';
   }
-  if (String(env.CODEX_SESSION_ID || '').trim()) return 'codex';
+  if (String(env.CODEX_THREAD_ID || '').trim() || String(env.CODEX_SESSION_ID || '').trim()) return 'codex';
   if (String(env.OPENCODE_SESSION_ID || '').trim()) return 'opencode';
   if (String(env.PI_SESSION_ID || '').trim()) return 'pi';
   return 'unknown';
@@ -99,12 +97,28 @@ function detectRuntime(env = process.env) {
  * @returns {string}  Non-empty session id, or "" if none present
  */
 function runtimeSessionId(env = process.env) {
+  return runtimeSessionCandidate(env).value;
+}
+
+/** Return the ordered native value together with the variable that supplied it. */
+function runtimeSessionCandidate(env = process.env) {
   env = env || {};
-  for (const varName of Object.values(RUNTIME_SESSION_ID_VARS)) {
-    const candidate = String(env[varName] || '').trim();
-    if (candidate) return candidate;
+  for (const [runtime, varNames] of Object.entries(RUNTIME_SESSION_ID_VARS)) {
+    for (const varName of varNames) {
+      const candidate = String(env[varName] || '').trim();
+      if (candidate) return { value: candidate, variable: varName, runtime };
+    }
   }
-  return '';
+  return { value: '', variable: '', runtime: '' };
+}
+
+/** Privacy-safe, domain-separated token for a Codex thread identifier. */
+function codexThreadToken(threadId) {
+  return `thread-${crypto.createHash('sha256')
+    .update('flow-agents:codex-thread:v1:')
+    .update(String(threadId))
+    .digest('hex')
+    .slice(0, 24)}`;
 }
 
 /**
@@ -362,11 +376,11 @@ function serializeActor(actor) {
  * @param {NodeJS.ProcessEnv} [env]  Environment to resolve from (default process.env)
  * @returns {{actor: string, source: string}}
  */
-function resolveActor(env = process.env) {
+function resolveActorIdentity(env = process.env) {
   env = env || {};
 
   if (env.FLOW_AGENTS_ACTOR_TEST_FORCE_UNRESOLVED === '1' && env.NODE_ENV === 'test') {
-    return { actor: '', source: 'test-forced-unresolved' };
+    return { actor: '', source: 'test-forced-unresolved', actorStruct: null };
   }
 
   const explicit = String(env.FLOW_AGENTS_ACTOR || '').trim();
@@ -392,15 +406,26 @@ function resolveActor(env = process.env) {
         );
       } catch { /* best-effort diagnostic only */ }
     } else {
-      return { actor: sanitizeSegment(explicit), source: 'explicit-override' };
+      const actor = sanitizeSegment(explicit);
+      return {
+        actor,
+        source: 'explicit-override',
+        // Explicit overrides deliberately retain their historical flat canonical key. The struct
+        // exists for durable descriptive records, but serializeActor(actorStruct) is not the key.
+        actorStruct: { runtime: 'explicit-override', session_id: actor, host: os.hostname() },
+      };
     }
   }
 
   const runtime = detectRuntime(env);
-  const sessionId = runtimeSessionId(env);
-  if (sessionId) {
-    const actor = serializeActor({ runtime, session_id: sessionId, host: os.hostname() });
-    return { actor, source: `runtime-session-id:${runtime}` };
+  const nativeSession = runtimeSessionCandidate(env);
+  if (nativeSession.value) {
+    const sessionId = nativeSession.variable === 'CODEX_THREAD_ID'
+      ? codexThreadToken(nativeSession.value)
+      : nativeSession.value;
+    const actorStruct = { runtime, session_id: sessionId, host: os.hostname() };
+    const actor = serializeActor(actorStruct);
+    return { actor, source: `runtime-session-id:${runtime}`, actorStruct };
   }
 
   // #398: CI-runtime tier — sits ABOVE process-ancestry (stable across every subprocess in a CI
@@ -411,17 +436,24 @@ function resolveActor(env = process.env) {
   // verify-hold gate to advisory for. A stable CI identity lets that gate ENFORCE instead.
   const ci = detectCiActor(env);
   if (ci && ci.session_id) {
-    const actor = serializeActor({ runtime: ci.runtime, session_id: ci.session_id, host: os.hostname() });
-    return { actor, source: `ci-runtime:${ci.runtime}` };
+    const actorStruct = { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname() };
+    const actor = serializeActor(actorStruct);
+    return { actor, source: `ci-runtime:${ci.runtime}`, actorStruct };
   }
 
   const seed = ancestorActorSeed();
   if (seed) {
-    const actor = serializeActor({ runtime, session_id: `anc-${seed}`, host: os.hostname() });
-    return { actor, source: 'process-ancestry' };
+    const actorStruct = { runtime: 'process-ancestry', session_id: `anc-${seed}`, host: os.hostname() };
+    const actor = serializeActor(actorStruct);
+    return { actor, source: 'process-ancestry', actorStruct };
   }
 
-  return { actor: '', source: 'unresolved' };
+  return { actor: '', source: 'unresolved', actorStruct: null };
+}
+
+function resolveActor(env = process.env) {
+  const { actor, source } = resolveActorIdentity(env);
+  return { actor, source };
 }
 
 /**
@@ -445,6 +477,7 @@ module.exports = {
   ancestorActorSeed,
   sanitizeSegment,
   serializeActor,
+  resolveActorIdentity,
   resolveActor,
   isUnresolvedActor,
 };

package/scripts/hooks/lib/continuation-turn-authority.js

@@ -0,0 +1,386 @@
+'use strict';
+
+// A transient, driver-owned capability for one adapter turn. Ed25519 proves
+// that the record was issued by the still-running driver's private key; it is
+// not a filesystem isolation boundary against a hostile same-UID process.
+
+const fs = require('fs');
+const path = require('path');
+const { createHash, generateKeyPairSync, randomBytes, randomUUID, sign, verify } = require('crypto');
+const { isDeepStrictEqual } = require('util');
+
+const SCHEMA_VERSION = '2.0';
+const FILE_NAME = 'active-turn.json';
+const MAX_ACTIVE_TURN_BYTES = 16 * 1024;
+const MAX_DRIVER_RECORD_BYTES = 1024 * 1024;
+const MAX_ASSIGNMENT_RECORD_BYTES = 1024 * 1024;
+const MAX_LOCK_RECORD_BYTES = 16 * 1024;
+const MAX_TIMEOUT_MS = 86_400_000;
+
+function activeTurnFile(sessionDir) {
+  return path.join(path.resolve(sessionDir), 'continuation-driver', FILE_NAME);
+}
+
+function issueActiveTurnAuthority(input) {
+  const sessionDir = path.resolve(input.sessionDir);
+  const parents = captureParents(sessionDir, true);
+  const issuedAt = input.now instanceof Date ? input.now : new Date();
+  const timeoutMs = input.timeoutMs;
+  assertPositiveInteger(timeoutMs, 'timeoutMs', 1, MAX_TIMEOUT_MS);
+  const assignmentActor = requiredString(input.assignmentActor, 'assignmentActor');
+  const assignmentActorStruct = requiredActorStruct(input.assignmentActorStruct, 'assignmentActorStruct');
+  const assignment = readActiveAssignment(sessionDir, parents, assignmentActor, assignmentActorStruct);
+  const keys = generateKeyPairSync('ed25519');
+  const turnSecret = randomBytes(32).toString('base64url');
+  const publicKey = keys.publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+  const publicKeyDigest = sha256(publicKey);
+  const record = {
+    schema_version: SCHEMA_VERSION,
+    run_id: requiredSafeRunId(input.runId, 'runId'),
+    definition_id: requiredString(input.definitionId, 'definitionId'),
+    issued_step: requiredString(input.currentStep, 'currentStep'),
+    iteration: requiredInteger(input.iteration, 'iteration', 1, 100),
+    max_turns: requiredInteger(input.maxTurns, 'maxTurns', 1, 100),
+    adapter_command_identity: requiredString(input.adapterCommandIdentity, 'adapterCommandIdentity'),
+    assignment_actor: assignmentActor,
+    assignment_actor_struct: assignmentActorStruct,
+    assignment_record_sha256: assignment.sha256,
+    driver_lock: {
+      pid: requiredInteger(input.lock.pid, 'lock.pid', 1, 2_147_483_647),
+      token: requiredString(input.lock.token, 'lock.token'),
+      created_at: requiredTimestamp(input.lock.created_at, 'lock.created_at'),
+    },
+    turn_secret_sha256: sha256(turnSecret),
+    public_key_spki_b64: publicKey,
+    public_key_digest: publicKeyDigest,
+    timeout_ms: timeoutMs,
+    issued_at: issuedAt.toISOString(),
+    expires_at: new Date(issuedAt.getTime() + timeoutMs).toISOString(),
+  };
+  if (record.run_id !== path.basename(sessionDir)) throw new Error('runId must match the session directory');
+  record.signature_b64 = sign(null, canonicalBytes(record), keys.privateKey).toString('base64');
+  writeRecord(sessionDir, parents, record);
+  return {
+    runId: record.run_id,
+    turnSecret,
+    publicKeyDigest,
+    record,
+    cleanup: () => removeActiveTurnAuthority(sessionDir, record.turn_secret_sha256, parents),
+  };
+}
+
+function removeActiveTurnAuthority(sessionDir, turnSecretSha256, issuedParents) {
+  try {
+    const parents = captureParents(sessionDir, false);
+    if (issuedParents && !sameParents(issuedParents, parents)) return false;
+    const file = activeTurnFile(sessionDir);
+    const loaded = readRegularJson(file, 'continuation active turn', parents, MAX_ACTIVE_TURN_BYTES);
+    if (loaded.value.turn_secret_sha256 !== turnSecretSha256) return false;
+    assertParentsStable(parents);
+    const current = fileIdentity(file, 'continuation active turn');
+    if (!sameIdentity(current, loaded.identity)) return false;
+    fs.unlinkSync(file);
+    assertParentsStable(parents);
+    return true;
+  } catch {
+    // Do not unlink through a changed parent. The signed record expires.
+    return false;
+  }
+}
+
+// Validates the signed, live assignment capability without consulting Flow's
+// current state. Public assignment-gated workflow commands use this narrow
+// fallback after ordinary actor resolution fails; Stop adds canonical-state
+// checks before treating its unfinished-gate warning as advisory.
+function validateSignedActiveTurnAssignmentAuthority(input) {
+  try {
+    const runId = requiredSafeRunId(input.runId, 'runId');
+    const turnSecret = requiredTurnSecret(input.turnSecret);
+    const sessionDir = path.resolve(input.sessionDir);
+    if (path.basename(sessionDir) !== runId) return invalid('run does not match session');
+    const parents = captureParents(sessionDir, false);
+    const record = readRegularJson(activeTurnFile(sessionDir), 'continuation active turn', parents, MAX_ACTIVE_TURN_BYTES).value;
+    validateRecord(record);
+    if (!equalText(record.run_id, runId)) return invalid('run does not match signed authority');
+    if (!equalText(record.turn_secret_sha256, sha256(turnSecret))) return invalid('turn secret does not match');
+    if (!validSignature(record)) return invalid('authority signature does not verify');
+    const assignment = readActiveAssignment(sessionDir, parents, record.assignment_actor, record.assignment_actor_struct);
+    if (!equalText(record.assignment_record_sha256, assignment.sha256)) return invalid('active assignment record changed');
+    const mission = readRegularJson(path.join(sessionDir, 'continuation-driver', 'state.json'), 'continuation driver state', parents, MAX_DRIVER_RECORD_BYTES).value;
+    if (!mission || mission.schema_version !== '1.0'
+      || mission.run_id !== record.run_id
+      || mission.definition_id !== record.definition_id
+      || mission.adapter_command_identity !== record.adapter_command_identity
+      || mission.max_turns !== record.max_turns
+      || mission.turns_started !== record.iteration
+      || mission.active_turn_step !== record.issued_step
+      || mission.active_turn_public_key_digest !== record.public_key_digest
+      || mission.status !== 'active') return invalid('driver mission does not match');
+    const lockFile = path.join(sessionDir, 'continuation-driver', 'locks', `${record.driver_lock.pid}-${record.driver_lock.token}.lock`);
+    const lock = readRegularJson(lockFile, 'continuation driver lock', parents, MAX_LOCK_RECORD_BYTES).value;
+    if (!lock || lock.schema_version !== '1.0'
+      || lock.pid !== record.driver_lock.pid
+      || lock.token !== record.driver_lock.token
+      || lock.created_at !== record.driver_lock.created_at
+      || !processAlive(lock.pid)) return invalid('driver lock is not live');
+    const now = input.now instanceof Date ? input.now : new Date();
+    if (now.getTime() < Date.parse(record.issued_at) || now.getTime() > Date.parse(record.expires_at)) return invalid('authority is expired');
+    assertParentsStable(parents);
+    return { valid: true, record };
+  } catch (error) {
+    return invalid(error && error.message ? error.message : 'authority is malformed');
+  }
+}
+
+function validateActiveTurnAuthority(input) {
+  const base = validateSignedActiveTurnAssignmentAuthority(input);
+  if (!base.valid) return base;
+  try {
+    const canonical = input.canonicalState;
+    const record = base.record;
+    // The issued step remains bound to the driver mission, while canonical
+    // Flow may advance during the adapter's Stop callback.
+    if (!canonical || canonical.status !== 'active'
+      || canonical.run_id !== record.run_id
+      || canonical.definition_id !== record.definition_id
+      || typeof canonical.current_step !== 'string' || !canonical.current_step) return invalid('canonical Flow state does not match');
+    return base;
+  } catch (error) {
+    return invalid(error && error.message ? error.message : 'canonical Flow state is malformed');
+  }
+}
+
+function invalid(reason) {
+  return { valid: false, reason };
+}
+
+function writeRecord(sessionDir, parents, record) {
+  assertParentsStable(parents);
+  const file = activeTurnFile(sessionDir);
+  if (fs.existsSync(file)) fileIdentity(file, 'continuation active turn');
+  const temp = path.join(path.dirname(file), `.${FILE_NAME}.${process.pid}.${randomUUID()}.tmp`);
+  let tempIdentity = null;
+  try {
+    fs.writeFileSync(temp, `${JSON.stringify(record)}\n`, { flag: 'wx', mode: 0o600 });
+    tempIdentity = fileIdentity(temp, 'continuation active turn temporary file');
+    assertParentsStable(parents);
+    fs.renameSync(temp, file);
+    assertParentsStable(parents);
+  } finally {
+    removeOwnedTemp(temp, tempIdentity, parents);
+  }
+}
+
+function removeOwnedTemp(temp, expected, parents) {
+  if (!expected) return;
+  try {
+    assertParentsStable(parents);
+    if (!sameIdentity(fileIdentity(temp, 'continuation active turn temporary file'), expected)) return;
+    fs.unlinkSync(temp);
+    assertParentsStable(parents);
+  } catch {
+    // Parent or temp identity changed. Leave the bounded temporary record for
+    // operator cleanup rather than unlinking through a replacement path.
+  }
+}
+
+function captureParents(sessionDir, create) {
+  const session = safeDirectory(path.resolve(sessionDir), 'session directory', create);
+  const driver = safeDirectory(path.join(session.path, 'continuation-driver'), 'continuation driver directory', create);
+  const locks = safeDirectory(path.join(driver.path, 'locks'), 'continuation driver locks directory', create);
+  const assignment = safeDirectory(path.join(path.dirname(session.path), 'assignment'), 'workflow assignment directory', false);
+  return { session, driver, locks, assignment };
+}
+
+function safeDirectory(target, label, create) {
+  if (create) fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(target);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${label} must be a non-symlink directory`);
+  const realpath = fs.realpathSync(target);
+  return { path: path.resolve(target), realpath, dev: stat.dev, ino: stat.ino };
+}
+
+function assertParentsStable(parents) {
+  for (const parent of [parents.session, parents.driver, parents.locks, parents.assignment]) {
+    const current = safeDirectory(parent.path, 'continuation authority parent', false);
+    if (!sameIdentity(parent, current) || current.realpath !== parent.realpath) throw new Error('continuation authority parent identity changed');
+  }
+}
+
+function sameParents(left, right) {
+  return ['session', 'driver', 'locks', 'assignment'].every((name) => sameIdentity(left[name], right[name]) && left[name].realpath === right[name].realpath);
+}
+
+function sameIdentity(left, right) {
+  return Boolean(left && right && left.dev === right.dev && left.ino === right.ino);
+}
+
+function readActiveAssignment(sessionDir, parents, actor, actorStruct) {
+  assertParentsStable(parents);
+  const artifactRoot = path.dirname(sessionDir);
+  const assignmentFile = path.join(parents.assignment.path, `${path.basename(sessionDir)}.json`);
+  const loaded = readRegularJson(assignmentFile, 'workflow assignment', parents, MAX_ASSIGNMENT_RECORD_BYTES);
+  const assignment = loaded.value;
+  if (!assignment || assignment.status !== 'claimed' || assignment.artifact_dir !== path.basename(sessionDir) || assignment.actor_key !== actor
+    || !isDeepStrictEqual(normalizeActorStruct(assignment.actor), normalizeActorStruct(actorStruct))) {
+    throw new Error('workflow assignment is not the active turn actor');
+  }
+  assertParentsStable(parents);
+  return { sha256: sha256(loaded.bytes) };
+}
+
+function readRegularJson(file, label, parents, maxBytes) {
+  if (parents) assertParentsStable(parents);
+  const expected = fileIdentity(file, label);
+  if (expected.size > maxBytes) throw new Error(`${label} exceeds maximum size`);
+  const noFollow = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+  try {
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.size > maxBytes || !sameIdentity(expected, opened)) throw new Error(`${label} identity changed while opening`);
+    const bytes = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd);
+    if (!sameIdentity(expected, after)) throw new Error(`${label} identity changed while reading`);
+    const final = fileIdentity(file, label);
+    if (!sameIdentity(expected, final)) throw new Error(`${label} identity changed after reading`);
+    const value = JSON.parse(bytes.toString('utf8'));
+    if (parents) assertParentsStable(parents);
+    return { value, bytes, identity: expected };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function fileIdentity(file, label) {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must be a bounded non-symlink regular file`);
+  return { dev: stat.dev, ino: stat.ino, size: stat.size };
+}
+
+function validateRecord(record) {
+  if (!record || typeof record !== 'object' || Array.isArray(record) || record.schema_version !== SCHEMA_VERSION) throw new Error('authority schema is unsupported');
+  for (const field of ['run_id', 'definition_id', 'issued_step', 'adapter_command_identity', 'assignment_actor', 'assignment_record_sha256', 'turn_secret_sha256', 'public_key_spki_b64', 'public_key_digest', 'signature_b64', 'issued_at', 'expires_at']) requiredString(record[field], field);
+  requiredSafeRunId(record.run_id, 'run_id');
+  requiredActorStruct(record.assignment_actor_struct, 'assignment_actor_struct');
+  if (!/^[0-9a-f]{64}$/i.test(record.assignment_record_sha256)
+    || !/^[0-9a-f]{64}$/i.test(record.turn_secret_sha256)
+    || !/^[0-9a-f]{64}$/i.test(record.public_key_digest)) throw new Error('authority digest is malformed');
+  requiredInteger(record.iteration, 'iteration', 1, 100);
+  requiredInteger(record.max_turns, 'max_turns', 1, 100);
+  if (record.iteration > record.max_turns) throw new Error('authority iteration exceeds mission budget');
+  assertPositiveInteger(record.timeout_ms, 'timeout_ms', 1, MAX_TIMEOUT_MS);
+  const issued = Date.parse(requiredTimestamp(record.issued_at, 'issued_at'));
+  const expires = Date.parse(requiredTimestamp(record.expires_at, 'expires_at'));
+  if (expires !== issued + record.timeout_ms) throw new Error('authority expiry does not match timeout');
+  if (!record.driver_lock || typeof record.driver_lock !== 'object' || Array.isArray(record.driver_lock)) throw new Error('authority lock is malformed');
+  requiredInteger(record.driver_lock.pid, 'driver_lock.pid', 1, 2_147_483_647);
+  requiredString(record.driver_lock.token, 'driver_lock.token');
+  requiredTimestamp(record.driver_lock.created_at, 'driver_lock.created_at');
+}
+
+function validSignature(record) {
+  const unsigned = { ...record };
+  const signature = Buffer.from(unsigned.signature_b64, 'base64');
+  delete unsigned.signature_b64;
+  const publicKey = { key: Buffer.from(unsigned.public_key_spki_b64, 'base64'), format: 'der', type: 'spki' };
+  return equalText(sha256(unsigned.public_key_spki_b64), unsigned.public_key_digest)
+    && verify(null, canonicalBytes(unsigned), publicKey, signature);
+}
+
+function canonicalBytes(value) {
+  return Buffer.from(JSON.stringify(canonicalize(value)), 'utf8');
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  return value;
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function equalText(left, right) {
+  const a = Buffer.from(String(left));
+  const b = Buffer.from(String(right));
+  return a.length === b.length && require('crypto').timingSafeEqual(a, b);
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 4096 || value.includes('\0')) throw new Error(`${label} must be a bounded non-empty string`);
+  return value;
+}
+
+function requiredSafeRunId(value, label) {
+  const text = requiredString(value, label);
+  if (!/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(text)) throw new Error(`${label} must be a safe Flow run id`);
+  return text;
+}
+
+function requiredTurnSecret(value) {
+  const text = requiredString(value, 'turnSecret');
+  if (!/^[A-Za-z0-9_-]{43}$/.test(text)) throw new Error('turnSecret must be a 32-byte base64url secret');
+  return text;
+}
+
+function requiredActorStruct(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an actor object`);
+  const keys = Object.keys(value);
+  if (!keys.every((key) => key === 'runtime' || key === 'session_id' || key === 'host' || key === 'human')
+    || !['runtime', 'session_id', 'host'].every((key) => Object.prototype.hasOwnProperty.call(value, key))) throw new Error(`${label} has unsupported fields`);
+  for (const key of ['runtime', 'session_id', 'host']) requiredBoundedActorField(value[key], `${label}.${key}`);
+  if (Object.prototype.hasOwnProperty.call(value, 'human') && value.human !== null) requiredBoundedActorField(value.human, `${label}.human`);
+  return {
+    runtime: value.runtime,
+    session_id: value.session_id,
+    host: value.host,
+    ...(Object.prototype.hasOwnProperty.call(value, 'human') ? { human: value.human } : {}),
+  };
+}
+
+function normalizeActorStruct(value) {
+  try {
+    const actor = requiredActorStruct(value, 'assignment actor');
+    return { ...actor, human: actor.human ?? null };
+  } catch {
+    return null;
+  }
+}
+
+function requiredBoundedActorField(value, label) {
+  if (typeof value !== 'string' || !value || value.length > 256 || /[\u0000-\u001f\u007f-\u009f]/.test(value)) throw new Error(`${label} must be a bounded non-empty string`);
+  return value;
+}
+
+function requiredInteger(value, label, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer from ${min} through ${max}`);
+  return value;
+}
+
+function assertPositiveInteger(value, label, min, max) {
+  requiredInteger(value, label, min, max);
+}
+
+function requiredTimestamp(value, label) {
+  const text = requiredString(value, label);
+  if (!Number.isFinite(Date.parse(text))) throw new Error(`${label} must be an ISO timestamp`);
+  return text;
+}
+
+module.exports = {
+  activeTurnFile,
+  issueActiveTurnAuthority,
+  removeActiveTurnAuthority,
+  validateActiveTurnAuthority,
+  validateSignedActiveTurnAssignmentAuthority,
+};