imprint-mcp 0.6.0 → 0.6.2

package/src/imprint/auth-compile-tools.ts

@@ -1,13 +1,10 @@
 /**
- * Auth-specific compile tools + verification, shared by both auth compile
- * drivers:
- *   - the in-process runAgentLoop path (auth-compile-agent.ts, anthropic-api)
- *   - the claude-cli / codex-cli path (mcp-compile-server.ts in auth mode)
- *
- * Keeping these in one module guarantees the agent sees an identical toolset
- * and identical external verification regardless of which provider drives it.
+ * Recording tools and contract-level verification shared by every auth compile
+ * provider. Site behavior is decided by the compile agent and encoded in the
+ * auth action program, not inferred here.
  */
 
+import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join as pathJoin } from 'node:path';
 import type { AgentTool } from './agent.ts';
@@ -18,50 +15,38 @@ import {
   buildReadResponseBodyTool,
   buildReadSessionSummaryTool,
   buildRunBashTool,
+  buildSearchRequestsTool,
   buildWriteFileTool,
 } from './compile-tools.ts';
-import { collectStatePlaceholders } from './runtime.ts';
-import { WorkflowSchema } from './types.ts';
-import type { Session } from './types.ts';
+import { recordedRequestMatchesWorkflow } from './recording-request.ts';
+import { captureHeader, captureValueMatches, jsonpath } from './request-capture.ts';
+import { type Session, type Workflow, WorkflowSchema } from './types.ts';
 
 type TeachCredentials = { site: string; values: Record<string, string> };
 
-/** Carried by the CLI compile drivers (claude-cli / codex-cli) to switch the
- *  shared spawn machinery from a data compile to an auth compile: the MCP
- *  server is launched in auth mode, and the agent gets the auth tool list +
- *  initial prompt. */
+export const AUTH_VERIFICATION_ATTEMPT_SENTINEL = '.auth-verification-attempt.json';
+
 export interface AuthCliCompileMode {
-  /** Site slug — the MCP server loads credentials from the store for it. */
   site: string;
-  /** JSON-serialized AuthToolPlan, passed to the MCP server. */
   authPlanJson: string;
-  /** Short tool names to pre-approve (the driver prefixes them per provider). */
   allowedTools: readonly string[];
-  /** The initial user message handed to the agent on turn 1. */
   initialPrompt: string;
 }
 
-/** Short names of every tool the auth compile agent may call (excluding the
- *  lifecycle done/give_up). Used by the claude-cli path to build --allowedTools.
- *  The agent SHAPES from the recording with the read/write tools and never logs
- *  in itself; live login happens only via the checkpoint tools (run_verification
- *  / prompt_user / wait_for_cooldown), which the orchestrator executes. */
 export const AUTH_COMPILE_TOOL_NAMES = [
   'read_session_summary',
+  'search_requests',
   'read_request',
   'read_response_body',
   'write_file',
   'read_file',
   'run_bash',
   'run_verification',
+  'inspect_verification_page',
   'prompt_user',
   'wait_for_cooldown',
 ] as const;
 
-/** Assemble the auth compile SHAPING toolset (read/write only — no live login).
- *  The checkpoint tools (run_verification/prompt_user/wait_for_cooldown) and
- *  done()/give_up() are appended by the driver (mcp-compile-server in auth mode)
- *  because they are orchestrator-mediated, not executed in this process. */
 export function buildAuthCompileTools(
   session: Session,
   toolDir: string,
@@ -71,139 +56,336 @@ export function buildAuthCompileTools(
   const context: CompileToolContext = { teachCredentials };
   return [
     buildReadSessionSummaryTool(session, context),
+    buildSearchRequestsTool(session),
     buildReadRequestTool(session),
     buildReadResponseBodyTool(session),
-    // Auth runs on cdp-replay only (a real headed browser that replays the
-    // recorded requests in-page) — there is no playbook rung in the auth path, so
-    // the agent emits workflow.json only. No playbook.yaml in the write allowlist.
     buildWriteFileTool(toolDir),
     buildReadFileTool(toolDir),
     buildRunBashTool(toolDir),
   ];
 }
 
-// ─── External verification ──────────────────────────────────────────────────
-
-/** Lightweight structural checks after the agent calls done(). The agent has
- *  already proven the workflow works live (AWAITING_2FA / ok:true from
- *  run_verification); this just guards the artifact's shape. Returns a list
- *  of failure strings (empty = passed).
- *
- *  `requiredSessionCaptures` carries the build plan's authTool captures: every
- *  durable token a downstream DATA tool consumes via `${credential.<name>}`
- *  (`usedAs` names the header it injects). For each one, the auth workflow MUST
- *  declare a matching `authConfig.sessionCapture` so the login persists it —
- *  otherwise the data tool's contracted auth header can never resolve at runtime. */
+export function authWorkflowPreflightFailures(
+  toolDir: string,
+  session?: Session,
+  requiredCredentialNames: readonly string[] = [],
+): string[] {
+  const workflowPath = pathJoin(toolDir, 'workflow.json');
+  if (!existsSync(workflowPath)) return ['workflow.json does not exist'];
+  return parseWorkflow(workflowPath, requiredCredentialNames, session).failures;
+}
+
 export function authExternalVerification(
   toolDir: string,
   requiredSessionCaptures: Array<{ name: string; usedAs?: string }> = [],
+  options: { requireLiveAttempt?: boolean; requiredCredentialNames?: readonly string[] } = {},
 ): string[] {
-  const failures: string[] = [];
   const workflowPath = pathJoin(toolDir, 'workflow.json');
+  if (!existsSync(workflowPath)) return ['workflow.json does not exist'];
 
-  if (!existsSync(workflowPath)) {
-    failures.push('workflow.json does not exist');
-    return failures;
+  const parsed = parseWorkflow(workflowPath, options.requiredCredentialNames);
+  if (!parsed.workflow) return parsed.failures;
+  const failures = [...parsed.failures];
+  const workflow = parsed.workflow;
+  const persisted = new Set(workflow.authConfig?.persist ?? []);
+
+  const missingContracts = requiredSessionCaptures.filter((capture) => {
+    const target = (capture.usedAs ?? '').toLowerCase();
+    return (
+      target.startsWith('header:') &&
+      target !== 'header:cookie' &&
+      target !== 'header:set-cookie' &&
+      !persisted.has(capture.name)
+    );
+  });
+  if (missingContracts.length > 0) {
+    failures.push(
+      `authConfig.persist must include downstream credential capture(s): ${missingContracts
+        .map((capture) => capture.name)
+        .join(', ')}`,
+    );
   }
 
+  if (options.requireLiveAttempt) {
+    failures.push(...liveAttemptFailures(toolDir, workflow));
+  }
+  return failures;
+}
+
+function parseWorkflow(
+  path: string,
+  requiredCredentialNames: readonly string[] = [],
+  session?: Session,
+): { workflow?: Workflow; failures: string[] } {
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(workflowPath, 'utf8'));
+    raw = JSON.parse(readFileSync(path, 'utf8'));
   } catch (err) {
-    failures.push(
-      `workflow.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    return failures;
+    return {
+      failures: [
+        `workflow.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+      ],
+    };
   }
 
   const parsed = WorkflowSchema.safeParse(raw);
   if (!parsed.success) {
-    failures.push(`workflow.json does not match WorkflowSchema: ${parsed.error.message}`);
+    return {
+      failures: [`workflow.json does not match WorkflowSchema: ${parsed.error.message}`],
+    };
+  }
+  return {
+    workflow: parsed.data,
+    failures: authProgramFailures(parsed.data, requiredCredentialNames, session),
+  };
+}
+
+function authProgramFailures(
+  workflow: Workflow,
+  requiredCredentialNames: readonly string[] = [],
+  session?: Session,
+): string[] {
+  const failures: string[] = [];
+  if (workflow.toolKind !== 'authenticate') {
+    failures.push(`workflow.toolKind must be "authenticate"`);
     return failures;
   }
+  const config = workflow.authConfig;
+  if (!config) return ['workflow.authConfig is missing'];
 
-  const workflow = parsed.data;
+  const reachableRequestIndexes = new Set(
+    Object.values(config.actions).flatMap((action) => action.steps.map((step) => step.request)),
+  );
+  const executable = JSON.stringify({
+    bootstrap: workflow.bootstrap,
+    requests: workflow.requests.filter((_, index) => reachableRequestIndexes.has(index)),
+  });
+  for (const name of requiredCredentialNames) {
+    if (!executable.includes(`\${credential.${name}}`)) {
+      failures.push(
+        `workflow must use planned credential ${JSON.stringify(name)} as \${credential.${name}} in an executable request or bootstrap`,
+      );
+    }
+  }
+  if (!config.actions[config.entry]) {
+    failures.push(`authConfig.entry references unknown action ${JSON.stringify(config.entry)}`);
+  }
 
-  if (workflow.toolKind !== 'authenticate') {
-    failures.push(
-      `workflow.toolKind must be 'authenticate', got '${workflow.toolKind ?? '(undefined)'}'`,
-    );
+  const actionParameter = workflow.parameters.find((parameter) => parameter.name === 'action');
+  const actionNames = Object.keys(config.actions);
+  if (!actionParameter) {
+    failures.push('workflow.parameters must declare the auth action selector');
+  } else {
+    const choices = new Set(actionParameter.choices ?? []);
+    const mismatchedChoices =
+      choices.size !== actionNames.length || actionNames.some((name) => !choices.has(name));
+    if (
+      actionParameter.type !== 'string' ||
+      actionParameter.default !== config.entry ||
+      mismatchedChoices
+    ) {
+      failures.push(
+        'workflow action parameter must be a string whose default is authConfig.entry and whose choices exactly match authConfig.actions',
+      );
+    }
   }
 
-  if (!workflow.requests || workflow.requests.length === 0) {
-    failures.push('workflow.requests is empty — auth tool needs at least one request');
+  const parameters = new Set(workflow.parameters.map((parameter) => parameter.name));
+  const captures = new Set<string>();
+  const captureOwners = new Map<
+    string,
+    {
+      request: Workflow['requests'][number];
+      capture: NonNullable<Workflow['requests'][number]['captures']>[number];
+    }
+  >();
+  for (const request of workflow.requests) {
+    for (const capture of request.captures ?? []) {
+      if (captures.has(capture.name)) {
+        failures.push(
+          `capture name ${JSON.stringify(capture.name)} must be unique across the auth workflow`,
+        );
+      }
+      captures.add(capture.name);
+      captureOwners.set(capture.name, { request, capture });
+    }
+  }
+  for (const action of Object.values(config.actions)) {
+    for (const step of action.steps) {
+      if (step.repeat) {
+        if (captures.has(step.repeat.until.name)) {
+          failures.push(
+            `capture name ${JSON.stringify(step.repeat.until.name)} must be unique across the auth workflow`,
+          );
+        }
+        captures.add(step.repeat.until.name);
+        const request = workflow.requests[step.request];
+        if (request) {
+          captureOwners.set(step.repeat.until.name, { request, capture: step.repeat.until });
+        }
+      }
+    }
   }
 
-  // Structural 2FA checks — assert the *shape* each structural case needs, never
-  // a channel name or response string. WorkflowSchema already constrains the
-  // enum to otp|push|none, so we only check that the artifact carries what the
-  // runtime needs to actually run that case.
-  const authConfig = workflow.authConfig;
-  if (!authConfig) {
-    failures.push('workflow.authConfig is missing');
-  } else if (authConfig.twoFactorType === 'push') {
-    // Push completes by polling an endpoint until a recording-grounded terminal
-    // (pollTerminal) resolves; without an endpoint there's nothing to poll.
-    if (!authConfig.pollEndpoint) {
-      failures.push("authConfig.twoFactorType is 'push' but authConfig.pollEndpoint is missing");
+  let hasSuccess = false;
+  for (const [name, action] of Object.entries(config.actions)) {
+    for (const parameter of action.parameters) {
+      if (!parameters.has(parameter)) {
+        failures.push(
+          `action ${JSON.stringify(name)} references unknown parameter ${JSON.stringify(parameter)}`,
+        );
+      }
     }
-  } else if (authConfig.twoFactorType === 'otp') {
-    // OTP completes via a second request carrying the live code.
-    if (!workflow.parameters.some((p) => p.name === 'otp_code')) {
-      failures.push("authConfig.twoFactorType is 'otp' but no 'otp_code' parameter is declared");
+    for (const [stepIndex, step] of action.steps.entries()) {
+      if (!workflow.requests[step.request]) {
+        failures.push(
+          `action ${JSON.stringify(name)} step ${stepIndex} references missing request ${step.request}`,
+        );
+      }
+      if (step.onError === 'retry' && !step.repeat) {
+        failures.push(
+          `action ${JSON.stringify(name)} step ${stepIndex} uses onError="retry" without repeat bounds`,
+        );
+      }
     }
-    // Every ${state.X} the completion requests read must be carried across the
-    // stateless initiate→submit_otp gap: either echoed via twoFactorContext or
-    // (re)produced by a capture on an initiate-phase request.
-    const initiateCount = authConfig.initiateRequestCount || 0;
-    const completionRequests = workflow.requests.slice(initiateCount);
-    const initiateCaptureNames = new Set<string>();
-    // slice(0, initiateCount) — NOT `initiateCount || undefined`: when the count is
-    // 0/unset there are NO initiate-phase requests, so `slice(0, 0)` must yield an
-    // empty set. `|| undefined` would make this `slice(0, undefined)` = ALL requests,
-    // counting completion-phase captures as "covered" and defeating the check.
-    for (const req of workflow.requests.slice(0, initiateCount)) {
-      for (const cap of req.captures ?? []) initiateCaptureNames.add(cap.name);
+    for (const evidence of action.outcome.evidence) {
+      if (!captures.has(evidence)) {
+        failures.push(
+          `action ${JSON.stringify(name)} references unknown evidence capture ${JSON.stringify(evidence)}`,
+        );
+      }
     }
-    const covered = new Set([...(authConfig.twoFactorContext ?? []), ...initiateCaptureNames]);
-    const uncovered = new Set<string>();
-    for (const req of completionRequests) {
-      for (const name of collectStatePlaceholders(req)) {
-        if (!covered.has(name)) uncovered.add(name);
+    if (action.outcome.type === 'pause') {
+      if (!config.actions[action.outcome.next]) {
+        failures.push(
+          `action ${JSON.stringify(name)} pauses to unknown action ${JSON.stringify(action.outcome.next)}`,
+        );
       }
+      for (const carried of action.outcome.carry) {
+        if (!captures.has(carried)) {
+          failures.push(
+            `action ${JSON.stringify(name)} carries unknown capture ${JSON.stringify(carried)}`,
+          );
+        }
+      }
+    } else {
+      hasSuccess = true;
     }
-    if (uncovered.size > 0) {
-      const refs = [...uncovered].map((n) => `\${state.${n}}`).join(', ');
+  }
+
+  if (!hasSuccess) failures.push('authConfig.actions has no success outcome');
+  for (const name of config.persist) {
+    if (!captures.has(name)) {
+      failures.push(`authConfig.persist references unknown capture ${JSON.stringify(name)}`);
+      continue;
+    }
+    const owner = captureOwners.get(name);
+    if (!owner) continue;
+    const { request, capture } = owner;
+    if (request.recordingRequestSeq === undefined) {
       failures.push(
-        `submit_otp requests reference ${refs} but those are neither listed in authConfig.twoFactorContext nor captured on an initiate-phase request — they will be undefined on the stateless submit_otp call`,
+        `persisted capture ${JSON.stringify(name)} must declare recordingRequestSeq on its producing request`,
+      );
+    } else if (session) {
+      const recorded = session.requests.find(
+        (candidate) => candidate.seq === request.recordingRequestSeq,
       );
+      if (!recorded) {
+        failures.push(
+          `persisted capture ${JSON.stringify(name)} references missing recorded request seq ${request.recordingRequestSeq}`,
+        );
+      } else if (!recordedRequestMatchesWorkflow(recorded, request)) {
+        failures.push(
+          `persisted capture ${JSON.stringify(name)} recordingRequestSeq ${request.recordingRequestSeq} does not match its workflow request`,
+        );
+      } else {
+        if (!recordedResponseProducesCapture(recorded, capture)) {
+          failures.push(
+            `persisted capture ${JSON.stringify(name)} is not produced by recorded request seq ${request.recordingRequestSeq}`,
+          );
+        }
+      }
     }
   }
+  if (!reachableSuccess(config.entry, config.actions)) {
+    failures.push('authConfig.entry cannot reach a success outcome');
+  }
+  return failures;
+}
 
-  // Downstream auth contract: every durable token a DATA tool consumes via
-  // ${credential.<name>} (a build-plan authTool capture whose usedAs is a header)
-  // must be persisted by a matching authConfig.sessionCapture, or the data tool's
-  // contracted auth header can never resolve at runtime. Cookies persist
-  // automatically, so only the NON-cookie header contracts are checked here.
-  const headerContracts = requiredSessionCaptures.filter((c) => {
-    const u = (c.usedAs ?? '').toLowerCase();
-    // Cookies persist automatically via the jar — only NON-cookie header tokens
-    // need a sessionCapture.
-    return u.startsWith('header:') && u !== 'header:cookie' && u !== 'header:set-cookie';
-  });
-  if (headerContracts.length > 0) {
-    const persisted = new Set((authConfig?.sessionCapture ?? []).map((c) => c.name));
-    const missing = headerContracts.filter((c) => !persisted.has(c.name));
-    if (missing.length > 0) {
-      failures.push(
-        `the build plan's data tools consume ${missing
-          .map((c) => `\`\${credential.${c.name}}\` (used as ${c.usedAs})`)
-          .join(', ')} but workflow.authConfig.sessionCapture does not persist ${
-          missing.length === 1 ? 'it' : 'them'
-        }. Add a sessionCapture for each so a SUCCESSFUL login stores the token as a durable credential the data tools can reuse — grounded in the login completion response (a body field or a response header), never invented.`,
-      );
+function recordedResponseProducesCapture(
+  request: Session['requests'][number],
+  capture: NonNullable<Workflow['requests'][number]['captures']>[number],
+): boolean {
+  const response = request.response;
+  if (!response || capture.source === 'cookie') return false;
+  const body = response.body ?? '';
+  let value: unknown;
+  if (capture.source === 'json') {
+    try {
+      value = jsonpath(JSON.parse(body), capture.path);
+    } catch {
+      return false;
+    }
+  } else if (capture.source === 'response_header') {
+    value =
+      capture.header.toLowerCase() === 'x-imprint-final-url'
+        ? request.url
+        : captureHeader(new Headers(response.headers), capture.header, capture.mode);
+  } else {
+    try {
+      value = new RegExp(capture.pattern).exec(body)?.[capture.group ?? 1];
+    } catch {
+      return false;
     }
   }
+  return captureValueMatches(value, capture.equals);
+}
 
-  return failures;
+function reachableSuccess(
+  entry: string,
+  actions: NonNullable<Workflow['authConfig']>['actions'],
+): boolean {
+  const seen = new Set<string>();
+  let current: string | undefined = entry;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const action: (typeof actions)[string] | undefined = actions[current];
+    if (!action) return false;
+    if (action.outcome.type === 'success') return true;
+    current = action.outcome.next;
+  }
+  return false;
+}
+
+export function authWorkflowHash(workflow: Workflow): string {
+  return createHash('sha256').update(JSON.stringify(workflow)).digest('hex');
+}
+
+function liveAttemptFailures(toolDir: string, workflow: Workflow): string[] {
+  const path = pathJoin(toolDir, AUTH_VERIFICATION_ATTEMPT_SENTINEL);
+  if (!existsSync(path)) {
+    return ['no live auth verification attempt was recorded; call run_verification before done'];
+  }
+
+  let attempt: { action?: unknown; ok?: unknown; workflowHash?: unknown };
+  try {
+    attempt = JSON.parse(readFileSync(path, 'utf8')) as typeof attempt;
+  } catch (err) {
+    return [
+      `live auth verification record is invalid: ${err instanceof Error ? err.message : String(err)}`,
+    ];
+  }
+  if (attempt.ok !== true || typeof attempt.action !== 'string') {
+    return ['the most recent live auth verification did not succeed'];
+  }
+  if (attempt.workflowHash !== authWorkflowHash(workflow)) {
+    return ['workflow.json changed after the most recent successful live auth verification'];
+  }
+  const action = workflow.authConfig?.actions[attempt.action];
+  return action?.outcome.type === 'success'
+    ? []
+    : [
+        `the most recent successful live action ${JSON.stringify(attempt.action)} does not declare a success outcome`,
+      ];
 }