imprint-mcp 0.7.1 → 0.7.2

package/src/imprint/mcp-session-recovery.ts

@@ -0,0 +1,167 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import type { ToolResult, Workflow } from './types.ts';
+
+const RecoveryPolicySchema = z
+  .object({
+    authTool: z.string().min(1),
+    protectedTools: z.array(z.string().min(1)).min(1),
+    startAction: z.string().min(1).optional(),
+    refreshAction: z.string().min(1).optional(),
+    timeoutMs: z.number().int().min(1).max(2_147_483_647).default(240_000),
+  })
+  .strict();
+
+export type RecoveryPolicy = z.infer<typeof RecoveryPolicySchema>;
+
+export function loadRecoveryPolicy(assetRoot: string, site: string): RecoveryPolicy | undefined {
+  const path = join(assetRoot, site, 'mcp-session-recovery.json');
+  try {
+    return RecoveryPolicySchema.parse(JSON.parse(readFileSync(path, 'utf8')));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+type AuthFailure = Extract<ToolResult, { ok: false }>;
+type RecoveryResult =
+  | { status: 'authenticated' }
+  | { status: 'blocked'; message: string }
+  | { status: 'manual'; action: string; state?: Record<string, unknown>; message: string };
+
+interface RecoveryHost {
+  signal: AbortSignal;
+  execute(action: string, state?: Record<string, unknown>): Promise<ToolResult>;
+  requestConsent?(action: string): Promise<boolean>;
+}
+
+function manual(action: string, pause?: AuthFailure): RecoveryResult {
+  return {
+    status: 'manual',
+    action,
+    state: pause?.continuation,
+    message: pause?.message ?? 'Sign-in needs to continue through the authentication tool.',
+  };
+}
+
+function isAuthenticated(result: ToolResult): boolean {
+  return (
+    result.ok &&
+    typeof result.data === 'object' &&
+    result.data !== null &&
+    'authenticated' in result.data &&
+    result.data.authenticated === true
+  );
+}
+
+export function missingAuthInputs(
+  workflow: Workflow,
+  action: string,
+  args: Record<string, unknown> = {},
+): string[] {
+  return (workflow.authConfig?.actions[action]?.parameters ?? []).filter(
+    (name) =>
+      args[name] === undefined &&
+      !workflow.parameters.some(
+        (parameter) => parameter.name === name && parameter.default !== undefined,
+      ),
+  );
+}
+
+/** Requests that need consent. Undefined means this action stays standalone. */
+export function unsafeAuthRequests(workflow: Workflow, action: string): Set<number> | undefined {
+  const actions = workflow.authConfig?.actions;
+  const steps = actions && Object.hasOwn(actions, action) ? actions[action]?.steps : undefined;
+  if (!steps) return undefined;
+
+  const unsafe = new Set<number>();
+  for (const step of steps) {
+    const request = workflow.requests[step.request];
+    if (request?.effect === 'safe' || request?.effect === 'idempotent') continue;
+    if (
+      request?.effect !== 'unsafe' ||
+      request.mode === 'navigate' ||
+      unsafe.has(step.request) ||
+      (step.repeat?.maxAttempts ?? 1) > 1
+    )
+      return undefined;
+    unsafe.add(step.request);
+  }
+  return unsafe;
+}
+
+export async function recoverSession(
+  workflow: Workflow,
+  policy: RecoveryPolicy,
+  host: RecoveryHost,
+): Promise<RecoveryResult> {
+  const config = workflow.authConfig;
+  if (!config?.actions) return { status: 'blocked', message: 'No compiled sign-in is available.' };
+
+  let action = policy.startAction ?? config.entry;
+  let pause: AuthFailure | undefined;
+  const refresh = policy.refreshAction === action ? undefined : policy.refreshAction;
+  const refreshAction =
+    refresh && Object.hasOwn(config.actions, refresh) ? config.actions[refresh] : undefined;
+  if (
+    refresh &&
+    refreshAction &&
+    !missingAuthInputs(workflow, refresh).length &&
+    refreshAction.steps.every(({ request }) => {
+      const effect = workflow.requests[request]?.effect;
+      return effect === 'safe' || effect === 'idempotent';
+    })
+  ) {
+    host.signal.throwIfAborted();
+    const result = await host.execute(refresh);
+    if (isAuthenticated(result)) return { status: 'authenticated' };
+    if (!result.ok && result.error === 'ACTION_REQUIRED' && result.nextAction) {
+      if (result.resume !== 'automatic') return manual(result.nextAction, result);
+      action = result.nextAction;
+      pause = result;
+    } else if (result.ok || result.error !== 'AUTH_EXPIRED') {
+      return { status: 'blocked', message: 'The saved session could not be refreshed.' };
+    }
+  }
+
+  const visited = new Set<string>();
+  const dispatchedUnsafe = new Set<number>();
+  while (!visited.has(action)) {
+    visited.add(action);
+    host.signal.throwIfAborted();
+    const unsafe = unsafeAuthRequests(workflow, action);
+    if (!unsafe || [...unsafe].some((request) => dispatchedUnsafe.has(request))) {
+      return { status: 'blocked', message: 'This action needs standalone manual sign-in.' };
+    }
+    if (missingAuthInputs(workflow, action).length) return manual(action, pause);
+
+    if (unsafe.size) {
+      if (!host.requestConsent) {
+        return {
+          status: 'blocked',
+          message: 'This client cannot request consent for a new approval. Use manual sign-in.',
+        };
+      }
+      if (!(await host.requestConsent(action))) {
+        return { status: 'blocked', message: 'Consent was declined or timed out.' };
+      }
+      for (const request of unsafe) dispatchedUnsafe.add(request);
+    }
+
+    host.signal.throwIfAborted();
+    const result = await host.execute(action, pause?.continuation);
+    if (isAuthenticated(result)) return { status: 'authenticated' };
+    if (result.ok || result.error !== 'ACTION_REQUIRED' || !result.nextAction) {
+      return {
+        status: 'blocked',
+        message: 'The compiled sign-in did not verify the session. Use the standalone auth tool.',
+      };
+    }
+    if (result.resume !== 'automatic') return manual(result.nextAction, result);
+    action = result.nextAction;
+    pause = result;
+  }
+  return { status: 'blocked', message: 'The compiled sign-in repeated an action.' };
+}

package/src/imprint/runtime.ts

@@ -7,6 +7,7 @@
 
 import { randomUUID } from 'node:crypto';
 import { dirname, resolve as pathResolve } from 'node:path';
+import { withAbortSignal } from './concurrency.ts';
 import {
   type CookieLookupConstraints,
   type RuntimeCookie,
@@ -34,6 +35,7 @@ import {
   resolveJsonCapture,
 } from './request-capture.ts';
 import type {
+  BrowserRequestInit,
   RequestCapture,
   RequestStageFact,
   StateCapability,
@@ -59,6 +61,8 @@ export interface CredentialStore {
   /** Version of the durable snapshot read by the host, before environment
    * overlays or browser mutations. Enables conditional cookie writeback. */
   durableRevision?: string;
+  /** Commit managed authentication against the snapshot used to start it. */
+  authCommitRevision?: string;
 }
 
 type NavigationOptions = NonNullable<WorkflowRequest['navigation']>;
@@ -173,6 +177,7 @@ export interface BrowserNavigationTransport {
 export async function loadCredentialStore(
   site: string,
   signal?: AbortSignal,
+  options?: { includeEmpty?: boolean },
 ): Promise<CredentialStore | null> {
   const view = await loadSiteCredentials(site, { signal });
   const store: CredentialStore = {
@@ -200,6 +205,7 @@ export async function loadCredentialStore(
   }
 
   if (
+    !options?.includeEmpty &&
     Object.keys(store.values).length === 0 &&
     store.cookies.length === 0 &&
     (store.storage?.length ?? 0) === 0
@@ -978,12 +984,15 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
       message: `Auth action ${JSON.stringify(actionName)} requires: ${missingParameters.join(', ')}.`,
     };
   }
+  const authSignal = credentials.authCommitRevision === undefined ? undefined : opts.signal;
   let requestTransform: RequestTransform | undefined;
   if (opts.workflow.requestTransformModule && opts.workflowPath) {
     try {
-      const mod = await importModuleFresh(
-        pathResolve(dirname(opts.workflowPath), opts.workflow.requestTransformModule),
+      const modulePath = pathResolve(
+        dirname(opts.workflowPath),
+        opts.workflow.requestTransformModule,
       );
+      const mod = await withAbortSignal(() => importModuleFresh(modulePath), authSignal);
       if (typeof mod.transform === 'function') {
         requestTransform = mod.transform as RequestTransform;
       }
@@ -1007,6 +1016,7 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
   let currentRequestIndex = 0;
   let phase: RequestStageFact['stage'] = 'preparation';
   let transportInvoked = false;
+  let managedUnsafeDispatches = 0;
   let httpStatus: number | undefined;
   const recordStage = (
     stage: RequestStageFact['stage'],
@@ -1025,6 +1035,18 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
     if (stageFacts.length > 32) stageFacts.shift();
   };
   const fail = (result: RuntimeErrorResult): RuntimeErrorResult => {
+    // A user can correct input after the provider rejects this submission.
+    // Managed MCP still requires consent before sending the corrected request.
+    const canCorrectInput =
+      managedUnsafeDispatches === 1 &&
+      action.parameters.length > 0 &&
+      phase === 'send' &&
+      transportInvoked &&
+      opts.workflow.requests[currentRequestIndex]?.effect === 'unsafe' &&
+      result.error !== 'NETWORK' &&
+      httpStatus !== undefined &&
+      httpStatus >= 400 &&
+      httpStatus < 500;
     return {
       ...result,
       requestStageFacts: [...stageFacts, ...(result.requestStageFacts ?? [])].slice(-32),
@@ -1039,7 +1061,12 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
         ...(httpStatus === undefined ? {} : { httpStatus }),
         ...result.authExecution,
       },
-      continuation: Object.keys(initialState).length > 0 ? initialState : undefined,
+      continuation:
+        (managedUnsafeDispatches === 0 || canCorrectInput) &&
+        (Object.keys(initialState).length > 0 ||
+          (credentials.authCommitRevision !== undefined && opts.initialState !== undefined))
+          ? initialState
+          : undefined,
     };
   };
 
@@ -1130,13 +1157,18 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
     const request = substituted.value;
     let navigation = req.navigation;
 
-    if (requestTransform) {
+    const transform = requestTransform;
+    if (transform) {
       try {
-        const transformed = await requestTransform(
-          request.method,
-          request.url,
-          responseSlots.map((slot) => slot.raw),
-          params,
+        const transformed = await withAbortSignal(
+          async () =>
+            transform(
+              request.method,
+              request.url,
+              responseSlots.map((slot) => slot.raw),
+              params,
+            ),
+          authSignal,
         );
         if (typeof transformed === 'string') request.url = transformed;
         else if (transformed) {
@@ -1237,7 +1269,10 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
       try {
         transportInvoked = true;
         phase = 'send';
-        response = await fetchFn(request.url, {
+        const managedUnsafe =
+          credentials.authCommitRevision !== undefined && req.effect === 'unsafe';
+        if (managedUnsafe) managedUnsafeDispatches++;
+        const init: BrowserRequestInit = {
           method: request.method,
           headers: request.headers,
           body: request.body,
@@ -1245,7 +1280,9 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
             ? AbortSignal.any([opts.signal, controller.signal])
             : controller.signal,
           redirect: 'follow',
-        });
+          ...(managedUnsafe ? { allowAmbiguousRetry: false } : {}),
+        };
+        response = await fetchFn(request.url, init);
         httpStatus = response.status;
         if (opts.browser)
           cookieJar.reconcileBrowserSnapshot(
@@ -1407,6 +1444,14 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
       if (opts.signal?.aborted) return cancellationFailure();
       if (!executed.ok) {
         lastFailure = executed.result;
+        if (
+          managedUnsafeDispatches > 0 &&
+          lastFailure.error === 'NETWORK' &&
+          transportInvoked &&
+          opts.workflow.requests[step.request]?.effect === 'unsafe'
+        ) {
+          return fail(lastFailure);
+        }
         if (step.onError === 'continue') {
           matched = true;
           break;
@@ -1497,7 +1542,8 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
     }
     const continuation = Object.fromEntries(outcome.carry.map((name) => [name, state[name]]));
     if (opts.signal?.aborted) return cancellationFailure();
-    const cookieFailure = await persistCookies();
+    const cookieFailure =
+      credentials.authCommitRevision === undefined ? await persistCookies() : undefined;
     if (opts.signal?.aborted) return cancellationFailure();
     if (cookieFailure && !opts.browser) return cookieFailure;
     const persistenceWarning = cookieFailure
@@ -1509,6 +1555,7 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
       error: 'ACTION_REQUIRED',
       message: `${outcome.message}${persistenceWarning}`,
       nextAction: outcome.next,
+      ...(outcome.resume ? { resume: outcome.resume } : {}),
       continuation,
       responseBodyPreview: lastResponse?.text.slice(0, 500),
     };
@@ -1536,6 +1583,7 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
     try {
       await commitSiteAuthState(opts.workflow.site, cookieJar.toJSON(), persistedSecrets, {
         signal: opts.signal,
+        expectedRevision: credentials.authCommitRevision,
       });
     } catch (err) {
       return opts.signal?.aborted

package/src/imprint/types.ts

@@ -251,6 +251,9 @@ const BootstrapCaptureSchema = z.discriminatedUnion('source', [
 ]);
 export type BootstrapCapture = z.infer<typeof BootstrapCaptureSchema>;
 
+/** Managed authentication can disable transport retry for an ambiguous dispatch. */
+export type BrowserRequestInit = RequestInit & { allowAmbiguousRetry?: false };
+
 const WorkflowRequestBaseSchema = z.object({
   method: z.string(),
   /** Sequence number of the captured request that grounds this outgoing
@@ -370,6 +373,7 @@ const AuthOutcomeSchema = z.discriminatedUnion('type', [
     .object({
       type: z.literal('pause'),
       next: z.string().min(1),
+      resume: z.literal('automatic').optional(),
       evidence: z.array(z.string().min(1)).optional().default([]),
       carry: z.array(z.string().min(1)).optional().default([]),
       message: z.string().min(1),
@@ -614,6 +618,7 @@ export type ToolResult<T = unknown> =
        *  unchanged on the next auth call. */
       continuation?: Record<string, unknown>;
       nextAction?: string;
+      resume?: 'automatic';
     };
 
 // ─── Cron config (input to `imprint cron`) ───────────────────────────────────