@epsilon-asi/actors 0.0.3 → 0.0.5

package/src/auth/LoginFlow.ts

@@ -0,0 +1,332 @@
+import { AuthError } from '../errors/AuthError.js';
+import { delay } from '../utils/delay.js';
+import { redact } from '../utils/redact.js';
+import type { ActorContext } from '../core/ActorContext.js';
+import type { FillTextOptions } from '../interaction/Forms.js';
+import { mergeHumanTypingOptions, type HumanTypingOptions } from '../interaction/HumanTyping.js';
+import type { Credentials, CredentialsProvider } from './CredentialsProvider.js';
+import { AuthStateDetector } from './AuthStateDetector.js';
+import {
+  hasStandardLoginSelectors,
+  type ClickLoginStep,
+  type FillCredentialLoginStep,
+  type LoginFillStep,
+  type LoginFlowDefinition,
+  type LoginStep,
+  type WaitForSelectorLoginStep
+} from './LoginFlow.types.js';
+
+export class LoginFlow {
+  constructor(
+    private readonly credentialsProvider: CredentialsProvider,
+    private readonly detector = new AuthStateDetector()
+  ) {}
+
+  async ensureAuthenticated(context: ActorContext, definition: LoginFlowDefinition): Promise<void> {
+    if (await this.detector.isLoggedIn(context, definition)) {
+      context.logger.info('Existing Chrome profile is already authenticated.', {
+        actorId: context.actor.id
+      });
+      return;
+    }
+
+    await this.login(context, definition);
+  }
+
+  async login(context: ActorContext, definition: LoginFlowDefinition): Promise<void> {
+    if (definition.credentials === undefined) {
+      throw new AuthError('Login is required, but no credentials ref was configured for this actor.', {
+        actorId: context.actor.id
+      });
+    }
+
+    const credentials = await this.credentialsProvider.getCredentials(definition.credentials);
+    const maxAttempts = definition.behavior?.maxAttempts ?? 1;
+    const steps = this.resolveSteps(definition);
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      context.logger.info('Starting login attempt.', {
+        actorId: context.actor.id,
+        attempt,
+        steps: steps.length,
+        credentials: redact({ username: credentials.username, password: credentials.password })
+      });
+
+      await context.nav.goto(definition.loginUrl);
+      await definition.hooks?.beforeLogin?.(context);
+
+      await this.executeSteps(context, definition, credentials, steps);
+
+      if ((definition.behavior?.waitAfterSubmitMs ?? 0) > 0) {
+        await delay(definition.behavior?.waitAfterSubmitMs ?? 0);
+      }
+
+      await this.throwIfConfiguredErrorIsVisible(context, definition);
+
+      if (await this.detector.isLoggedIn(context, definition)) {
+        context.logger.info('Login succeeded.', { actorId: context.actor.id, attempt });
+        return;
+      }
+    }
+
+    throw new AuthError('Login did not result in an authenticated session.', {
+      actorId: context.actor.id,
+      details: { maxAttempts }
+    });
+  }
+
+  private resolveSteps(definition: LoginFlowDefinition): LoginStep[] {
+    if (definition.steps !== undefined && definition.steps.length > 0) {
+      return definition.steps;
+    }
+
+    if (!hasStandardLoginSelectors(definition.selectors)) {
+      throw new AuthError(
+        'Login flow requires either selectors.username/password/submit for a simple login or an ordered steps array for a multi-step login.'
+      );
+    }
+
+    const submitStep: ClickLoginStep = {
+      type: 'click',
+      name: 'submit',
+      selector: definition.selectors.submit,
+      submit: true,
+      navigationOptions: { waitUntil: 'domcontentloaded' },
+      checkForError: false
+    };
+
+    if (definition.behavior?.submitCausesNavigation !== undefined) {
+      submitStep.waitForNavigation = definition.behavior.submitCausesNavigation;
+    }
+
+    return [
+      {
+        type: 'fill',
+        name: 'username',
+        selector: definition.selectors.username,
+        credential: 'username'
+      },
+      {
+        type: 'fill',
+        name: 'password',
+        selector: definition.selectors.password,
+        credential: 'password'
+      },
+      submitStep
+    ];
+  }
+
+  private async executeSteps(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    credentials: Credentials,
+    steps: LoginStep[]
+  ): Promise<void> {
+    for (const [index, step] of steps.entries()) {
+      const label = this.stepLabel(step, index);
+      context.logger.debug('Executing login step.', {
+        actorId: context.actor.id,
+        step: label,
+        type: step.type
+      });
+
+      if (step.type === 'hook') {
+        await step.run(context);
+        continue;
+      }
+
+      await step.before?.(context);
+
+      if (step.type === 'fill') {
+        await this.executeFillStep(context, definition, credentials, step);
+      } else if (step.type === 'click') {
+        await this.executeClickStep(context, definition, step, label);
+      } else {
+        await this.executeWaitForSelectorStep(context, definition, step, label);
+      }
+
+      await step.after?.(context);
+    }
+  }
+
+  private async executeFillStep(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    credentials: Credentials,
+    step: LoginFillStep
+  ): Promise<void> {
+    const value = await this.resolveFillValue(step, credentials, context);
+    await context.forms.fillText(step.selector, value, this.buildFillOptions(definition, step));
+
+    if (this.isCredentialFillStep(step)) {
+      if (step.credential === 'username') {
+        await definition.hooks?.afterUsername?.(context);
+      } else {
+        await definition.hooks?.afterPassword?.(context);
+      }
+    }
+  }
+
+  private async executeClickStep(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    step: ClickLoginStep,
+    label: string
+  ): Promise<void> {
+    if (step.submit) {
+      await definition.hooks?.beforeSubmit?.(context);
+    }
+
+    if (step.waitForNavigation) {
+      await Promise.all([
+        context.page.waitForNavigation(step.navigationOptions ?? { waitUntil: 'domcontentloaded' }),
+        context.cursor.click(step.selector, this.clickOptions(step))
+      ]);
+    } else {
+      await context.cursor.click(step.selector, this.clickOptions(step));
+    }
+
+    if (step.submit) {
+      await definition.hooks?.afterSubmit?.(context);
+    }
+
+    if ((step.waitAfterMs ?? 0) > 0) {
+      await delay(step.waitAfterMs ?? 0);
+    }
+
+    if (this.shouldCheckForStepError(definition, step.checkForError)) {
+      await this.throwIfConfiguredErrorIsVisible(context, definition, label);
+    }
+
+    if (step.waitForSelector !== undefined) {
+      await this.waitForNextStageSelector(context, definition, step, label);
+    }
+  }
+
+  private async executeWaitForSelectorStep(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    step: WaitForSelectorLoginStep,
+    label: string
+  ): Promise<void> {
+    await this.waitForRequiredSelector(context, definition, step.selector, label, step.timeoutMs);
+
+    if (this.shouldCheckForStepError(definition, step.checkForError)) {
+      await this.throwIfConfiguredErrorIsVisible(context, definition, label);
+    }
+  }
+
+  private async waitForNextStageSelector(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    step: ClickLoginStep,
+    label: string
+  ): Promise<void> {
+    await this.waitForRequiredSelector(
+      context,
+      definition,
+      step.waitForSelector!,
+      label,
+      step.waitForSelectorTimeoutMs
+    );
+  }
+
+  private async waitForRequiredSelector(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    selector: string,
+    label: string,
+    timeoutMs: number | undefined
+  ): Promise<void> {
+    try {
+      await context.page.waitFor(selector, timeoutMs === undefined ? undefined : { timeout: timeoutMs });
+    } catch (error) {
+      await this.throwIfConfiguredErrorIsVisible(context, definition, label);
+      throw new AuthError(`Login step ${label} did not reach expected selector: ${selector}`, {
+        actorId: context.actor.id,
+        details: { selector, step: label, cause: error }
+      });
+    }
+  }
+
+  private buildFillOptions(definition: LoginFlowDefinition, step: LoginFillStep): FillTextOptions {
+    const options: FillTextOptions = {
+      required: step.required ?? true,
+      clear: step.clearFieldBeforeTyping ?? definition.behavior?.clearFieldBeforeTyping ?? true,
+      clearMethod: step.clearMethod ?? 'select-delete'
+    };
+
+    if (step.timeoutMs !== undefined) {
+      options.timeoutMs = step.timeoutMs;
+    }
+    if (step.clickBeforeTyping !== undefined) {
+      options.clickBeforeTyping = step.clickBeforeTyping;
+    }
+
+    const typing = this.mergeStepTyping(definition.behavior?.typing, step.typing);
+    if (typing !== undefined) {
+      options.typing = typing;
+    }
+
+    return options;
+  }
+
+  private mergeStepTyping(
+    behaviorTyping: HumanTypingOptions | undefined,
+    stepTyping: HumanTypingOptions | undefined
+  ): HumanTypingOptions | undefined {
+    if (behaviorTyping === undefined && stepTyping === undefined) return undefined;
+    return mergeHumanTypingOptions(behaviorTyping, stepTyping);
+  }
+
+  private async resolveFillValue(
+    step: LoginFillStep,
+    credentials: Credentials,
+    context: ActorContext
+  ): Promise<string> {
+    if (this.isCredentialFillStep(step)) {
+      return credentials[step.credential];
+    }
+
+    if (typeof step.value === 'function') {
+      return step.value(credentials, context);
+    }
+
+    return step.value;
+  }
+
+  private isCredentialFillStep(step: LoginFillStep): step is FillCredentialLoginStep {
+    return 'credential' in step;
+  }
+
+  private clickOptions(step: ClickLoginStep): { timeoutMs?: number } | undefined {
+    if (step.timeoutMs === undefined) return undefined;
+    return { timeoutMs: step.timeoutMs };
+  }
+
+  private shouldCheckForStepError(definition: LoginFlowDefinition, checkForError: boolean | undefined): boolean {
+    return definition.selectors.errorMessage !== undefined && (checkForError ?? true);
+  }
+
+  private async throwIfConfiguredErrorIsVisible(
+    context: ActorContext,
+    definition: LoginFlowDefinition,
+    stepLabel?: string
+  ): Promise<void> {
+    if (definition.selectors.errorMessage === undefined) return;
+
+    const hasError = await context.page.exists(definition.selectors.errorMessage, {
+      timeout: definition.behavior?.errorTimeoutMs ?? 500
+    });
+
+    if (!hasError) return;
+
+    const message = await context.page.text(definition.selectors.errorMessage);
+    const prefix = stepLabel === undefined ? 'Login failed' : `Login failed during step ${stepLabel}`;
+    throw new AuthError(`${prefix}: ${message}`, { actorId: context.actor.id });
+  }
+
+  private stepLabel(step: LoginStep, index: number): string {
+    return step.name === undefined ? `#${index + 1}` : `"${step.name}"`;
+  }
+}

package/src/auth/LoginFlow.types.ts

@@ -0,0 +1,141 @@
+import type { WaitForOptions } from 'puppeteer-core';
+import type { ActorContext } from '../core/ActorContext.js';
+import type { ClearFieldStrategy } from '../interaction/FieldClearer.js';
+import type { HumanTypingOptions } from '../interaction/HumanTyping.js';
+import type { CredentialRef, Credentials } from './CredentialsProvider.js';
+
+export interface LoginResultSelectors {
+  loggedInSignal: string;
+  errorMessage?: string;
+}
+
+export interface StandardLoginSelectors extends LoginResultSelectors {
+  username: string;
+  password: string;
+  submit: string;
+}
+
+export type LoginSelectors = LoginResultSelectors | StandardLoginSelectors;
+
+export type AuthHook = (context: ActorContext) => Promise<void> | void;
+export type AuthVerifier = (context: ActorContext) => Promise<boolean> | boolean;
+export type CredentialField = keyof Pick<Credentials, 'username' | 'password'>;
+export type LoginStepValueResolver = (credentials: Credentials, context: ActorContext) => Promise<string> | string;
+
+interface LoginStepBase {
+  /** Optional diagnostic name used in logs and errors. */
+  name?: string;
+  before?: AuthHook;
+  after?: AuthHook;
+}
+
+export interface FillCredentialLoginStep extends LoginStepBase {
+  type: 'fill';
+  selector: string;
+  /** Choose which credential value to type into this field. */
+  credential: CredentialField;
+  required?: boolean;
+  timeoutMs?: number;
+  clickBeforeTyping?: boolean;
+  /** Overrides LoginBehavior.clearFieldBeforeTyping for this individual field. */
+  clearFieldBeforeTyping?: boolean;
+  clearMethod?: ClearFieldStrategy;
+  /** Overrides LoginBehavior.typing for this individual field. */
+  typing?: HumanTypingOptions;
+}
+
+export interface FillValueLoginStep extends LoginStepBase {
+  type: 'fill';
+  selector: string;
+  /** Literal value or value resolver for non-credential login fields, such as tenant or workspace. */
+  value: string | LoginStepValueResolver;
+  required?: boolean;
+  timeoutMs?: number;
+  clickBeforeTyping?: boolean;
+  /** Overrides LoginBehavior.clearFieldBeforeTyping for this individual field. */
+  clearFieldBeforeTyping?: boolean;
+  clearMethod?: ClearFieldStrategy;
+  /** Overrides LoginBehavior.typing for this individual field. */
+  typing?: HumanTypingOptions;
+}
+
+export type LoginFillStep = FillCredentialLoginStep | FillValueLoginStep;
+
+export interface ClickLoginStep extends LoginStepBase {
+  type: 'click';
+  selector: string;
+  timeoutMs?: number;
+  waitForNavigation?: boolean;
+  navigationOptions?: WaitForOptions;
+  /** Wait for the next login-stage selector after the click, e.g. a password field. */
+  waitForSelector?: string;
+  waitForSelectorTimeoutMs?: number;
+  waitAfterMs?: number;
+  /** Marks this click as the final submit action, so legacy beforeSubmit/afterSubmit hooks are applied. */
+  submit?: boolean;
+  /** Defaults to true for click steps when selectors.errorMessage is configured. */
+  checkForError?: boolean;
+}
+
+export interface WaitForSelectorLoginStep extends LoginStepBase {
+  type: 'waitForSelector';
+  selector: string;
+  timeoutMs?: number;
+  /** Defaults to true when selectors.errorMessage is configured. */
+  checkForError?: boolean;
+}
+
+export interface HookLoginStep {
+  type: 'hook';
+  name?: string;
+  run: AuthHook;
+}
+
+export type LoginStep = LoginFillStep | ClickLoginStep | WaitForSelectorLoginStep | HookLoginStep;
+
+export interface LoginBehavior {
+  authCheckUrl?: string;
+  /** Used by the legacy single-submit login flow when steps are omitted. */
+  submitCausesNavigation?: boolean;
+  waitAfterSubmitMs?: number;
+  maxAttempts?: number;
+  loggedInTimeoutMs?: number;
+  errorTimeoutMs?: number;
+  /**
+   * Selects and deletes existing login field contents before typing.
+   * Defaults to true for the standardized login flow and every fill step.
+   */
+  clearFieldBeforeTyping?: boolean;
+  /** Optional per-login typing profile. Defaults to approximately 65 WPM with tiny jitter. */
+  typing?: HumanTypingOptions;
+}
+
+export interface LoginFlowDefinition {
+  loginUrl: string;
+  /**
+   * For a simple one-page login, include username/password/submit/loggedInSignal.
+   * For a multi-step login, loggedInSignal is required and username/password/submit are optional
+   * because the ordered `steps` array supplies the fields and buttons.
+   */
+  selectors: LoginSelectors;
+  credentials?: CredentialRef;
+  /** Optional ordered flow for username-first/password-second or other multi-stage forms. */
+  steps?: LoginStep[];
+  behavior?: LoginBehavior;
+  hooks?: {
+    beforeLogin?: AuthHook;
+    afterUsername?: AuthHook;
+    afterPassword?: AuthHook;
+    beforeSubmit?: AuthHook;
+    afterSubmit?: AuthHook;
+    verifyLoggedIn?: AuthVerifier;
+  };
+}
+
+export function defineLoginFlow(definition: LoginFlowDefinition): LoginFlowDefinition {
+  return definition;
+}
+
+export function hasStandardLoginSelectors(selectors: LoginSelectors): selectors is StandardLoginSelectors {
+  return 'username' in selectors && 'password' in selectors && 'submit' in selectors;
+}

package/src/auth/SessionStore.ts

@@ -0,0 +1,21 @@
+export interface StoredSession {
+  cookies?: unknown[];
+  localStorage?: Record<string, string>;
+  savedAt: string;
+}
+
+export interface SessionStore {
+  load(actorId: string, accountId?: string): Promise<StoredSession | null>;
+  save(actorId: string, session: StoredSession, accountId?: string): Promise<void>;
+  clear(actorId: string, accountId?: string): Promise<void>;
+}
+
+export class NoopSessionStore implements SessionStore {
+  async load(): Promise<StoredSession | null> {
+    return null;
+  }
+
+  async save(): Promise<void> {}
+
+  async clear(): Promise<void> {}
+}

package/src/auth/index.ts

@@ -0,0 +1,5 @@
+export * from './AuthStateDetector.js';
+export * from './CredentialsProvider.js';
+export * from './LoginFlow.js';
+export * from './LoginFlow.types.js';
+export * from './SessionStore.js';