@codemation/host 0.8.0 → 0.9.0

package/src/infrastructure/persistence/PrismaMigrationOperations.ts

@@ -0,0 +1,401 @@
+import type { Client } from "@libsql/client";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AppPersistenceConfig } from "../../presentation/config/AppConfig";
+
+/**
+ * Contains all runtime logic for deploying Prisma migrations.
+ * This class is loaded lazily via `await import(...)` from PrismaMigrationDeployer
+ * so that the dynamic fs/path/createRequire operations never appear in the
+ * static module graph visible to the Turbopack / Next.js NFT tracer.
+ */
+export class PrismaMigrationOperations {
+  private static readonly normalizedRuntimeMigrationName = "20260407140000_run_normalized_persistence";
+  private readonly require = createRequire(import.meta.url);
+
+  async deployPersistence(persistence: AppPersistenceConfig, env?: Readonly<NodeJS.ProcessEnv>): Promise<void> {
+    if (persistence.kind === "none") {
+      return;
+    }
+    if (persistence.kind === "postgresql") {
+      await this.deployPostgres({ databaseUrl: persistence.databaseUrl, env });
+      return;
+    }
+    await this.deploySqlite({ databaseFilePath: persistence.databaseFilePath, env });
+  }
+
+  async deploy(args: Readonly<{ databaseUrl: string; env?: Readonly<NodeJS.ProcessEnv> }>): Promise<void> {
+    await this.deployPostgres(args);
+  }
+
+  resolvePackageRoot(env: Readonly<NodeJS.ProcessEnv> = process.env): string {
+    const configuredRoot = env.CODEMATION_HOST_PACKAGE_ROOT;
+    if (configuredRoot) {
+      return configuredRoot;
+    }
+    let currentDirectory = path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth += 1) {
+      if (existsSync(path.join(currentDirectory, "prisma", "schema.postgresql.prisma"))) {
+        return currentDirectory;
+      }
+      const parentDirectory = path.dirname(currentDirectory);
+      if (parentDirectory === currentDirectory) {
+        break;
+      }
+      currentDirectory = parentDirectory;
+    }
+    throw new Error(`Could not locate prisma/schema.postgresql.prisma near ${fileURLToPath(import.meta.url)}.`);
+  }
+
+  private async deploySqlite(
+    args: Readonly<{ databaseFilePath: string; env?: Readonly<NodeJS.ProcessEnv> }>,
+  ): Promise<void> {
+    await this.ensureSqliteParentDirectoryExists(args.databaseFilePath);
+    const databaseUrl = this.sqliteFilePathToDatabaseUrl(args.databaseFilePath);
+    try {
+      await this.deployWithProvider({
+        provider: "sqlite",
+        databaseUrl,
+        env: args.env,
+      });
+    } catch (error) {
+      const recovered = await this.tryRecoverPartiallyAppliedNormalizedRuntimeMigration({
+        databaseFilePath: args.databaseFilePath,
+        databaseUrl,
+        env: args.env,
+        error,
+      });
+      if (!recovered) {
+        throw error;
+      }
+    }
+    await this.cleanupNormalizedRuntimeLegacyArtifacts(args.databaseFilePath);
+  }
+
+  private async deployPostgres(
+    args: Readonly<{ databaseUrl: string; env?: Readonly<NodeJS.ProcessEnv> }>,
+  ): Promise<void> {
+    await this.deployWithProvider({
+      provider: "postgresql",
+      databaseUrl: args.databaseUrl,
+      env: args.env,
+    });
+  }
+
+  private async deployWithProvider(
+    args: Readonly<{
+      provider: "postgresql" | "sqlite";
+      databaseUrl: string;
+      env?: Readonly<NodeJS.ProcessEnv>;
+    }>,
+  ): Promise<void> {
+    await this.runPrismaCommand({
+      prismaArgs: ["migrate", "deploy"],
+      provider: args.provider,
+      databaseUrl: args.databaseUrl,
+      env: args.env,
+    });
+  }
+
+  private async resolveAppliedMigration(
+    args: Readonly<{
+      provider: "postgresql" | "sqlite";
+      databaseUrl: string;
+      migrationName: string;
+      env?: Readonly<NodeJS.ProcessEnv>;
+    }>,
+  ): Promise<void> {
+    await this.runPrismaCommand({
+      prismaArgs: ["migrate", "resolve", "--applied", args.migrationName],
+      provider: args.provider,
+      databaseUrl: args.databaseUrl,
+      env: args.env,
+    });
+  }
+
+  private async runPrismaCommand(
+    args: Readonly<{
+      prismaArgs: string[];
+      provider: "postgresql" | "sqlite";
+      databaseUrl: string;
+      env?: Readonly<NodeJS.ProcessEnv>;
+    }>,
+  ): Promise<void> {
+    const resolverEnv = { ...process.env, ...(args.env ?? {}) };
+    const prismaConfigPath = this.resolveAbsolutePrismaConfigPath(resolverEnv);
+    await new Promise<void>((resolve, reject) => {
+      const command = spawn(
+        process.execPath,
+        [...[this.resolvePrismaCliPath(resolverEnv), ...args.prismaArgs], "--config", path.basename(prismaConfigPath)],
+        {
+          cwd: path.dirname(prismaConfigPath),
+          env: this.createProcessEnvironment(args.databaseUrl, args.provider, args.env),
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+      let stdout = "";
+      let stderr = "";
+      command.stdout.on("data", (chunk: Buffer | string) => {
+        stdout += chunk.toString();
+      });
+      command.stderr.on("data", (chunk: Buffer | string) => {
+        stderr += chunk.toString();
+      });
+      command.once("error", (error) => {
+        reject(error);
+      });
+      command.once("close", (exitCode) => {
+        if (exitCode === 0) {
+          resolve();
+          return;
+        }
+        reject(this.createDeployError(exitCode, stdout, stderr));
+      });
+    });
+  }
+
+  private async tryRecoverPartiallyAppliedNormalizedRuntimeMigration(
+    args: Readonly<{
+      databaseFilePath: string;
+      databaseUrl: string;
+      env?: Readonly<NodeJS.ProcessEnv>;
+      error: unknown;
+    }>,
+  ): Promise<boolean> {
+    if (!this.isRecoverableNormalizedRuntimeMigrationError(args.error)) {
+      return false;
+    }
+    const repaired = await this.repairPartiallyAppliedNormalizedRuntimeSqliteDatabase(args.databaseFilePath);
+    if (!repaired) {
+      return false;
+    }
+    await this.resolveAppliedMigration({
+      provider: "sqlite",
+      databaseUrl: args.databaseUrl,
+      migrationName: PrismaMigrationOperations.normalizedRuntimeMigrationName,
+      env: args.env,
+    });
+    await this.deployWithProvider({
+      provider: "sqlite",
+      databaseUrl: args.databaseUrl,
+      env: args.env,
+    });
+    return true;
+  }
+
+  private isRecoverableNormalizedRuntimeMigrationError(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    return (
+      error.message.includes("Error: P3009") &&
+      error.message.includes(PrismaMigrationOperations.normalizedRuntimeMigrationName)
+    );
+  }
+
+  private async repairPartiallyAppliedNormalizedRuntimeSqliteDatabase(databaseFilePath: string): Promise<boolean> {
+    // Lazy import: @libsql/client pulls in platform-specific native bindings that confuse the
+    // Next.js / Turbopack module tracer (forcing the whole project to be traced via NFT). This
+    // recovery path is rarely needed, so defer the load until it's actually invoked.
+    const { createClient } = await import("@libsql/client");
+    const client = createClient({ url: this.sqliteFilePathToDatabaseUrl(databaseFilePath) });
+    try {
+      const failedMigration = await this.hasActiveFailedMigrationRecord(
+        client,
+        PrismaMigrationOperations.normalizedRuntimeMigrationName,
+      );
+      if (!failedMigration) {
+        return false;
+      }
+      const runColumns = await this.readSqliteTableColumns(client, "Run");
+      const hasNormalizedRunShape =
+        runColumns.has("finished_at") &&
+        runColumns.has("revision") &&
+        runColumns.has("outputs_by_node_json") &&
+        !runColumns.has("state_json");
+      if (!hasNormalizedRunShape) {
+        return false;
+      }
+      await this.ensureNormalizedRuntimeRepairArtifacts(client);
+      return true;
+    } finally {
+      client.close();
+    }
+  }
+
+  private async hasActiveFailedMigrationRecord(client: Client, migrationName: string): Promise<boolean> {
+    const result = await client.execute({
+      sql: [
+        'SELECT 1 AS "has_failed"',
+        'FROM "_prisma_migrations"',
+        'WHERE "migration_name" = ?',
+        '  AND "finished_at" IS NULL',
+        '  AND "rolled_back_at" IS NULL',
+        "LIMIT 1",
+      ].join(" "),
+      args: [migrationName],
+    });
+    return result.rows.length > 0;
+  }
+
+  private async readSqliteTableColumns(client: Client, tableName: string): Promise<Set<string>> {
+    const result = await client.execute(`PRAGMA table_info("${tableName}")`);
+    return new Set(result.rows.map((row) => String(row.name)));
+  }
+
+  private async ensureNormalizedRuntimeRepairArtifacts(client: Client): Promise<void> {
+    await client.execute(`
+      CREATE TABLE IF NOT EXISTS "RunWorkItem" (
+        "work_item_id" TEXT NOT NULL PRIMARY KEY,
+        "run_id" TEXT NOT NULL,
+        "workflow_id" TEXT NOT NULL,
+        "status" TEXT NOT NULL,
+        "target_node_id" TEXT NOT NULL,
+        "batch_id" TEXT NOT NULL,
+        "queue_name" TEXT,
+        "claim_token" TEXT,
+        "claimed_by" TEXT,
+        "claimed_at" TEXT,
+        "available_at" TEXT NOT NULL,
+        "enqueued_at" TEXT NOT NULL,
+        "completed_at" TEXT,
+        "failed_at" TEXT,
+        "source_instance_id" TEXT,
+        "parent_instance_id" TEXT,
+        "items_in" INTEGER NOT NULL,
+        "inputs_by_port_json" TEXT NOT NULL,
+        "error_json" TEXT,
+        CONSTRAINT "RunWorkItem_run_id_fkey" FOREIGN KEY ("run_id") REFERENCES "Run"("run_id") ON DELETE CASCADE ON UPDATE CASCADE
+      )
+    `);
+    await client.execute(`
+      CREATE INDEX IF NOT EXISTS "RunWorkItem_run_id_status_available_at_idx"
+      ON "RunWorkItem"("run_id", "status", "available_at")
+    `);
+    await client.execute(`
+      CREATE INDEX IF NOT EXISTS "RunWorkItem_run_id_target_node_id_batch_id_idx"
+      ON "RunWorkItem"("run_id", "target_node_id", "batch_id")
+    `);
+    await client.execute(`
+      CREATE TABLE IF NOT EXISTS "RunSlotProjection" (
+        "run_id" TEXT NOT NULL PRIMARY KEY,
+        "workflow_id" TEXT NOT NULL,
+        "revision" INTEGER NOT NULL,
+        "updated_at" TEXT NOT NULL,
+        "slot_states_json" TEXT NOT NULL,
+        CONSTRAINT "RunSlotProjection_run_id_fkey" FOREIGN KEY ("run_id") REFERENCES "Run"("run_id") ON DELETE CASCADE ON UPDATE CASCADE
+      )
+    `);
+    await client.execute(`
+      CREATE INDEX IF NOT EXISTS "RunSlotProjection_workflow_id_updated_at_idx"
+      ON "RunSlotProjection"("workflow_id", "updated_at")
+    `);
+    await client.execute(`
+      INSERT OR IGNORE INTO "RunSlotProjection" (
+        "run_id",
+        "workflow_id",
+        "revision",
+        "updated_at",
+        "slot_states_json"
+      )
+      SELECT
+        "run_id",
+        "workflow_id",
+        "revision",
+        "updated_at",
+        json_object('slotStatesByNodeId', json('{}'))
+      FROM "Run"
+    `);
+  }
+
+  private async cleanupNormalizedRuntimeLegacyArtifacts(databaseFilePath: string): Promise<void> {
+    const { createClient } = await import("@libsql/client");
+    const client = createClient({ url: this.sqliteFilePathToDatabaseUrl(databaseFilePath) });
+    try {
+      const runColumns = await this.readSqliteTableColumns(client, "Run");
+      const hasNormalizedRunShape =
+        runColumns.has("finished_at") &&
+        runColumns.has("revision") &&
+        runColumns.has("outputs_by_node_json") &&
+        !runColumns.has("state_json");
+      if (!hasNormalizedRunShape) {
+        return;
+      }
+      const runSlotProjectionColumns = await this.readSqliteTableColumns(client, "RunSlotProjection");
+      await client.execute('DROP TABLE IF EXISTS "Run_legacy"');
+      if (runSlotProjectionColumns.size > 0) {
+        await client.execute('DROP TABLE IF EXISTS "RunProjection"');
+      }
+    } finally {
+      client.close();
+    }
+  }
+
+  private sqliteFilePathToDatabaseUrl(databaseFilePath: string): string {
+    return `file:${path.resolve(databaseFilePath)}`;
+  }
+
+  private createProcessEnvironment(
+    databaseUrl: string,
+    provider: "postgresql" | "sqlite",
+    env?: Readonly<NodeJS.ProcessEnv>,
+  ): NodeJS.ProcessEnv {
+    return {
+      ...process.env,
+      ...(env ?? {}),
+      DATABASE_URL: databaseUrl,
+      CODEMATION_PRISMA_PROVIDER: provider,
+    };
+  }
+
+  private resolvePrismaCliPath(env: Readonly<NodeJS.ProcessEnv>): string {
+    const configuredPath = env.CODEMATION_PRISMA_CLI_PATH;
+    if (configuredPath && existsSync(configuredPath)) {
+      return configuredPath;
+    }
+    const packageRoot = this.resolvePackageRoot(env);
+    const packageManagerCandidates = [
+      path.resolve(process.cwd(), "node_modules", "prisma", "build", "index.js"),
+      path.resolve(packageRoot, "node_modules", "prisma", "build", "index.js"),
+    ];
+    for (const candidate of packageManagerCandidates) {
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    try {
+      return this.require.resolve("prisma/build/index.js", {
+        paths: [process.cwd(), packageRoot],
+      });
+    } catch {
+      throw new Error(
+        "Unable to resolve the Prisma CLI required for startup migrations. Ensure `prisma` is installed.",
+      );
+    }
+  }
+
+  private resolveAbsolutePrismaConfigPath(env: Readonly<NodeJS.ProcessEnv>): string {
+    const configuredPath = env.CODEMATION_PRISMA_CONFIG_PATH;
+    const packageRoot = this.resolvePackageRoot(env);
+    if (configuredPath) {
+      return path.isAbsolute(configuredPath) ? configuredPath : path.resolve(packageRoot, configuredPath);
+    }
+    return path.resolve(packageRoot, "prisma.config.ts");
+  }
+
+  private async ensureSqliteParentDirectoryExists(databaseFilePath: string): Promise<void> {
+    await mkdir(path.dirname(databaseFilePath), { recursive: true });
+  }
+
+  private createDeployError(exitCode: number | null, stdout: string, stderr: string): Error {
+    const output = stderr.trim() || stdout.trim();
+    if (!output) {
+      return new Error(`Prisma migrate deploy failed during startup with exit code ${exitCode ?? "unknown"}.`);
+    }
+    return new Error(`Prisma migrate deploy failed during startup with exit code ${exitCode ?? "unknown"}.\n${output}`);
+  }
+}

package/src/infrastructure/persistence/PrismaWorkflowRunRepository.ts

@@ -173,6 +173,7 @@ export class PrismaWorkflowRunRepository implements WorkflowRunRepository, Workf
       control: this.parseJson(row.controlJson),
       workflowSnapshot: this.parseJson(row.workflowSnapshotJson),
       mutableState: this.parseJson(row.mutableStateJson),
+      ...this.loadHitlState(row.hitlStateJson),
       policySnapshot: this.parseJson(row.policySnapshotJson),
       engineCounters: this.parseJson(row.engineCountersJson),
       status: row.status as PersistedRunState["status"],
@@ -416,6 +417,7 @@ export class PrismaWorkflowRunRepository implements WorkflowRunRepository, Workf
           policySnapshotJson: state.policySnapshot ? JSON.stringify(state.policySnapshot) : null,
           engineCountersJson: state.engineCounters ? JSON.stringify(state.engineCounters) : null,
           mutableStateJson: state.mutableState ? JSON.stringify(state.mutableState) : null,
+          hitlStateJson: this.buildHitlStateJson(state),
           outputsByNodeJson: JSON.stringify(this.buildPersistedOutputsByNode(state)),
         },
       });
@@ -596,6 +598,43 @@ export class PrismaWorkflowRunRepository implements WorkflowRunRepository, Workf
     };
   }
 
+  /**
+   * Serialize HITL state fields into the dedicated `hitl_state_json` column.
+   * Returns null when none of the HITL fields are populated.
+   */
+  private buildHitlStateJson(state: PersistedRunState): string | null {
+    const hasHitl =
+      (state.suspension && state.suspension.length > 0) ||
+      state.pendingResume !== undefined ||
+      state.reason !== undefined;
+    if (!hasHitl) return null;
+    return JSON.stringify({
+      ...(state.suspension && state.suspension.length > 0 ? { suspension: state.suspension } : {}),
+      ...(state.pendingResume !== undefined ? { pendingResume: state.pendingResume } : {}),
+      ...(state.reason !== undefined ? { reason: state.reason } : {}),
+    });
+  }
+
+  /**
+   * Load HITL state (suspension array, pendingResume context, halt reason) from the
+   * dedicated `hitl_state_json` column.
+   */
+  private loadHitlState(
+    hitlStateJson: string | null,
+  ): Pick<PersistedRunState, "suspension" | "pendingResume" | "reason"> {
+    const parsed = this.parseJson<{
+      suspension?: PersistedRunState["suspension"];
+      pendingResume?: PersistedRunState["pendingResume"];
+      reason?: PersistedRunState["reason"];
+    }>(hitlStateJson);
+    if (!parsed) return {};
+    return {
+      suspension: parsed.suspension,
+      pendingResume: parsed.pendingResume,
+      reason: parsed.reason,
+    };
+  }
+
   private buildWorkItems(state: PersistedRunState, nowIso: string): Prisma.RunWorkItemCreateManyInput[] {
     const rows: Prisma.RunWorkItemCreateManyInput[] = [];
     for (const [index, entry] of (state.queue ?? []).entries()) {

package/src/mcp/AgentMcpIntegrationImpl.ts

@@ -102,7 +102,11 @@ export class AgentMcpIntegrationImpl implements AgentMcpIntegration {
    * Looks up the credential binding for the MCP connection node and verifies the
    * referenced credential instance still exists.
    */
-  private async resolveCredentialInstanceId(workflowId: string, agentNodeId: string, serverId: string): Promise<string> {
+  private async resolveCredentialInstanceId(
+    workflowId: string,
+    agentNodeId: string,
+    serverId: string,
+  ): Promise<string> {
     const mcpNodeId = ConnectionNodeIdFactory.mcpConnectionNodeId(agentNodeId, serverId);
     const binding = await this.credentialStore.getBinding({ workflowId, nodeId: mcpNodeId, slotKey: "credential" });
     if (!binding) {

package/src/pairing/HmacNonceStore.ts

@@ -0,0 +1,14 @@
+/**
+ * Seam for durable HMAC replay-protection nonce storage (T6 security fix).
+ *
+ * The default in-process store (InMemoryHmacNonceStore) clears on restart, allowing
+ * replay within the timestamp window. PrismaHmacNonceStore provides durability.
+ */
+export interface HmacNonceStore {
+  /**
+   * Atomically record a nonce if it has not been seen before.
+   * Returns `true` if the nonce was new (request should proceed),
+   * `false` if the nonce was already present (replay — reject).
+   */
+  recordIfNew(nonce: string, expiresAt: Date): Promise<boolean>;
+}

package/src/pairing/HmacNonceStoreToken.ts

@@ -0,0 +1,4 @@
+import type { TypeToken } from "@codemation/core";
+import type { HmacNonceStore } from "./HmacNonceStore";
+
+export const HmacNonceStoreToken = Symbol.for("codemation.pairing.HmacNonceStore") as TypeToken<HmacNonceStore>;

package/src/pairing/HmacRequestSigner.ts

@@ -9,9 +9,18 @@ export interface SignedHeaders {
 
 @injectable()
 export class HmacRequestSigner {
-  constructor(@inject(PairingConfigToken) private readonly config: PairingConfig) {}
+  constructor(@inject(PairingConfigToken, { isOptional: true }) private readonly config: PairingConfig | null = null) {}
 
   sign(method: string, urlOrPath: string, body: string): SignedHeaders {
+    if (this.config === null) {
+      // Should never happen in managed mode (PairingConfig is registered then). In non-managed
+      // mode this signer should never be called — callers like `PairedFetch` are themselves
+      // only reachable via `ControlPlaneCatalogFetcher` whose poll loop checks `pairingConfig`.
+      // If we land here, a CP-bound call escaped that guard.
+      throw new Error(
+        "HmacRequestSigner.sign called without a registered PairingConfig — workspace is not in managed mode.",
+      );
+    }
     const ts = Math.floor(Date.now() / 1000);
     const nonce = randomBytes(16).toString("base64");
 

package/src/pairing/InMemoryHmacNonceStore.ts

@@ -0,0 +1,24 @@
+import { injectable } from "@codemation/core";
+import type { HmacNonceStore } from "./HmacNonceStore";
+
+/**
+ * In-memory HMAC nonce store for unit tests and non-managed mode.
+ *
+ * NOTE: Nonces are lost on process restart; this is intentional for non-managed
+ * mode where replay risk is low. Use PrismaHmacNonceStore in managed mode.
+ */
+@injectable()
+export class InMemoryHmacNonceStore implements HmacNonceStore {
+  private readonly store = new Map<string, number>();
+
+  async recordIfNew(nonce: string, expiresAt: Date): Promise<boolean> {
+    const nowSec = Math.floor(Date.now() / 1000);
+    // Prune expired entries on each call (mirrors original in-process behaviour)
+    for (const [key, expirySec] of this.store.entries()) {
+      if (expirySec <= nowSec) this.store.delete(key);
+    }
+    if (this.store.has(nonce)) return false;
+    this.store.set(nonce, Math.floor(expiresAt.getTime() / 1000));
+    return true;
+  }
+}

package/src/pairing/IncomingHmacVerifier.ts

@@ -2,19 +2,41 @@ import { createHmac, createHash, timingSafeEqual } from "node:crypto";
 import { inject, injectable } from "@codemation/core";
 import type { PairingConfig, PairingVerificationResult } from "./pairing.types";
 import { PairingConfigToken } from "./PairingConfigToken";
+import type { HmacNonceStore } from "./HmacNonceStore";
+import { HmacNonceStoreToken } from "./HmacNonceStoreToken";
 
 /**
  * Verifies incoming HMAC-signed requests from the control plane.
  * Mirrors the control-plane HmacVerifier — both sides follow docs/pairing-protocol.md.
+ *
+ * Security (T6): The nonce store is injected and defaults to PrismaHmacNonceStore in
+ * managed mode so replay protection survives process restarts within the 300-second
+ * timestamp window.
  */
 @injectable()
 export class IncomingHmacVerifier {
-  private readonly usedNonces = new Map<string, number>();
   private readonly nonceTtlSeconds = 600; // 10 minutes
 
-  constructor(@inject(PairingConfigToken) private readonly config: PairingConfig) {}
+  constructor(
+    @inject(PairingConfigToken, { isOptional: true }) private readonly config: PairingConfig | null = null,
+    @inject(HmacNonceStoreToken) private readonly nonceStore: HmacNonceStore,
+  ) {}
 
-  verify(method: string, url: string, body: string, authHeader: string | null): PairingVerificationResult {
+  async verify(
+    method: string,
+    url: string,
+    body: string,
+    authHeader: string | null,
+  ): Promise<PairingVerificationResult> {
+    if (this.config === null) {
+      // Same shape as HmacRequestSigner — verifier is reachable via the DI graph even in
+      // non-managed mode (lazy CodemationHonoApiApp construction pulls every registered handler).
+      // We accept construction without PairingConfig and throw only when verify() is actually
+      // called, which shouldn't happen in non-managed mode (internal HMAC routes aren't mounted).
+      throw new Error(
+        "IncomingHmacVerifier.verify called without a registered PairingConfig — workspace is not in managed mode.",
+      );
+    }
     if (!this.config.pairingSecret || this.config.pairingSecret.trim().length === 0) {
       throw new Error("IncomingHmacVerifier: pairingSecret is not configured — cannot verify HMAC requests.");
     }
@@ -47,10 +69,10 @@ export class IncomingHmacVerifier {
       return { failure: "signature" };
     }
 
-    this.pruneExpiredNonces(nowSec);
     const nonceKey = `${parts.workspaceId}:${parts.nonce}`;
-    if (this.usedNonces.has(nonceKey)) return { failure: "replay" };
-    this.usedNonces.set(nonceKey, nowSec + this.nonceTtlSeconds);
+    const nonceExpiresAt = new Date((nowSec + this.nonceTtlSeconds) * 1000);
+    const isNew = await this.nonceStore.recordIfNew(nonceKey, nonceExpiresAt);
+    if (!isNew) return { failure: "replay" };
 
     return { workspaceId: parts.workspaceId };
   }
@@ -73,10 +95,4 @@ export class IncomingHmacVerifier {
     if (!v || !workspaceId || !ts || !nonce || !sig) return null;
     return { v, workspaceId, ts: Number(ts), nonce, sig };
   }
-
-  private pruneExpiredNonces(nowSec: number): void {
-    for (const [key, expiry] of this.usedNonces.entries()) {
-      if (expiry <= nowSec) this.usedNonces.delete(key);
-    }
-  }
 }

package/src/pairing/InternalHmacAuthMiddleware.ts

@@ -17,7 +17,7 @@ export class InternalHmacAuthMiddleware {
     return async (c: Context, next: Next) => {
       const body = c.req.method === "GET" || c.req.method === "HEAD" ? "" : await c.req.text();
 
-      const result = this.verifier.verify(c.req.method, c.req.url, body, c.req.header("authorization") ?? null);
+      const result = await this.verifier.verify(c.req.method, c.req.url, body, c.req.header("authorization") ?? null);
 
       if ("failure" in result) {
         return c.json({ error: "Unauthorized" }, 401);

package/src/pairing/index.ts

@@ -6,6 +6,9 @@ export { InternalHmacAuthMiddleware } from "./InternalHmacAuthMiddleware";
 export { InternalPingRegistrar } from "./InternalPingRegistrar";
 export { PairingConfigFactory } from "./PairingConfigFactory";
 export { PairingConfigToken } from "./PairingConfigToken";
+export type { HmacNonceStore } from "./HmacNonceStore";
+export { HmacNonceStoreToken } from "./HmacNonceStoreToken";
+export { InMemoryHmacNonceStore } from "./InMemoryHmacNonceStore";
 export type {
   PairingConfig,
   PairingVerificationResult,

package/src/presentation/http/ApiPaths.ts

@@ -132,6 +132,10 @@ export class ApiPaths {
     return `${this.credentialsBasePath}/instances`;
   }
 
+  static credentialApps(): string {
+    return `${this.credentialsBasePath}/apps`;
+  }
+
   static credentialInstance(instanceId: string, withSecrets?: boolean): string {
     const base = `${this.credentialInstances()}/${encodeURIComponent(instanceId)}`;
     return withSecrets ? `${base}?withSecrets=1` : base;
@@ -279,4 +283,14 @@ export class ApiPaths {
   static internalAuthBootstrap(): string {
     return `${this.bootstrapBasePath}/auth/internal`;
   }
+
+  /** Token-authenticated: resume a suspended HITL task. */
+  static hitlTaskResume(taskId: string): string {
+    return `${this.apiBasePath}/hitl/tasks/${encodeURIComponent(taskId)}/resume`;
+  }
+
+  /** Session-authenticated: record a decision on a suspended HITL task. */
+  static hitlTaskDecide(taskId: string): string {
+    return `${this.apiBasePath}/hitl/tasks/${encodeURIComponent(taskId)}/decide`;
+  }
 }

package/src/presentation/http/hono/HonoHttpAnonymousRoutePolicyRegistry.ts

@@ -35,6 +35,10 @@ export class HonoHttpAnonymousRoutePolicy {
     if (pathname === ApiPaths.whitelabelLogo()) {
       return true;
     }
+    // HITL token-authenticated resume endpoint — token is the auth, no session required
+    if (/^\/api\/hitl\/tasks\/[^/]+\/resume$/.test(pathname)) {
+      return true;
+    }
     return false;
   }
 }

package/src/presentation/http/hono/registrars/CredentialHonoApiRouteRegistrar.ts

@@ -8,6 +8,7 @@ export class CredentialHonoApiRouteRegistrar implements HonoApiRouteRegistrar {
   constructor(@inject(CredentialHttpRouteHandler) private readonly handler: CredentialHttpRouteHandler) {}
 
   register(app: Hono): void {
+    app.get("/credentials/apps", (_c) => this.handler.getCredentialApps());
     app.get("/credentials/types", (_c) => this.handler.getCredentialTypes());
     app.get("/credentials/env-status", (_c) => this.handler.getCredentialFieldEnvStatus());
     app.get("/credentials/instances", (_c) => this.handler.getCredentialInstances());