latchkey 0.1.0

package/src/playwrightUtils.ts

@@ -0,0 +1,143 @@
+/**
+ * Playwright utility functions for browser automation.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Browser, BrowserContext, Page, Locator } from 'playwright';
+import { EncryptedStorage } from './encryptedStorage.js';
+
+export interface BrowserWithContext {
+  readonly browser: Browser;
+  readonly context: BrowserContext;
+}
+
+/**
+ * Run a callback with a browser context initialized from encrypted storage state.
+ * After the callback completes, persists browser state back to encrypted storage.
+ */
+export async function withTempBrowserContext<T>(
+  encryptedStorage: EncryptedStorage,
+  browserStatePath: string,
+  callback: (state: BrowserWithContext) => Promise<T>
+): Promise<T> {
+  const tempDir = mkdtempSync(join(tmpdir(), 'latchkey-browser-state-'));
+  const tempFilePath = join(tempDir, 'browser_state.json');
+
+  let initialStorageState: string | undefined;
+  if (existsSync(browserStatePath)) {
+    const content = encryptedStorage.readFile(browserStatePath);
+    if (content !== null) {
+      writeFileSync(tempFilePath, content, { encoding: 'utf-8', mode: 0o600 });
+      initialStorageState = tempFilePath;
+    }
+  }
+
+  const { chromium: chromiumBrowser } = await import('playwright');
+  const browser = await chromiumBrowser.launch({ headless: false });
+
+  try {
+    const contextOptions: { storageState?: string } = {};
+    if (initialStorageState !== undefined) {
+      contextOptions.storageState = initialStorageState;
+    }
+    const context = await browser.newContext(contextOptions);
+
+    const result = await callback({ browser, context });
+
+    // Persist browser state back to encrypted storage
+    await context.storageState({ path: tempFilePath });
+    const content = readFileSync(tempFilePath, 'utf-8');
+    encryptedStorage.writeFile(browserStatePath, content);
+
+    return result;
+  } finally {
+    await browser.close();
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+// Typing delay range in milliseconds (min, max) to simulate human-like typing
+const TYPING_DELAY_MIN_MS = 30;
+const TYPING_DELAY_MAX_MS = 100;
+
+/**
+ * Type text character by character with random delays to simulate human typing.
+ *
+ * This triggers proper JavaScript input events that some websites require,
+ * unlike fill() which sets the value directly.
+ */
+export async function typeLikeHuman(page: Page, locator: Locator, text: string): Promise<void> {
+  await locator.click();
+  for (const character of text) {
+    await locator.pressSequentially(character);
+    const delay =
+      Math.floor(Math.random() * (TYPING_DELAY_MAX_MS - TYPING_DELAY_MIN_MS + 1)) +
+      TYPING_DELAY_MIN_MS;
+    await page.waitForTimeout(delay);
+  }
+}
+
+// Script that creates the spinner overlay, designed to run in browser context
+function createSpinnerOverlayScript(serviceName: string): string {
+  return `
+(() => {
+  if (document.getElementById('latchkey-spinner-overlay')) return;
+  const overlay = document.createElement('div');
+  overlay.id = 'latchkey-spinner-overlay';
+  overlay.innerHTML = \`
+    <style>
+      #latchkey-spinner-overlay {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        background: #f5f5f5;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+        z-index: 2147483647;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        pointer-events: none;
+      }
+      #latchkey-spinner-overlay .spinner {
+        width: 50px;
+        height: 50px;
+        border: 4px solid #e0e0e0;
+        border-top-color: #007bff;
+        border-radius: 50%;
+        animation: latchkey-spin 1s linear infinite;
+      }
+      #latchkey-spinner-overlay .message {
+        margin-top: 20px;
+        color: #555;
+        font-size: 16px;
+      }
+      @keyframes latchkey-spin {
+        to { transform: rotate(360deg); }
+      }
+    </style>
+    <div class="spinner"></div>
+    <div class="message">Finalizing ${serviceName} login...</div>
+  \`;
+  document.body.appendChild(overlay);
+})()
+`;
+}
+
+/**
+ * Show a spinner overlay that hides page content from the user.
+ * The overlay persists across page navigations within the browser context.
+ */
+export async function showSpinnerPage(context: BrowserContext, serviceName: string): Promise<void> {
+  const spinnerPage = await context.newPage();
+  await spinnerPage.evaluate(createSpinnerOverlayScript(serviceName));
+  await spinnerPage.bringToFront();
+}

package/src/registry.ts

@@ -0,0 +1,35 @@
+/**
+ * Service registry for looking up services by name or URL.
+ */
+
+import { Service, SLACK, DISCORD, DROPBOX, GITHUB, LINEAR } from './services/index.js';
+
+export class Registry {
+  readonly services: readonly Service[];
+
+  constructor(services: readonly Service[]) {
+    this.services = services;
+  }
+
+  getByName(name: string): Service | null {
+    for (const service of this.services) {
+      if (service.name === name) {
+        return service;
+      }
+    }
+    return null;
+  }
+
+  getByUrl(url: string): Service | null {
+    for (const service of this.services) {
+      for (const baseApiUrl of service.baseApiUrls) {
+        if (url.startsWith(baseApiUrl)) {
+          return service;
+        }
+      }
+    }
+    return null;
+  }
+}
+
+export const REGISTRY = new Registry([SLACK, DISCORD, DROPBOX, GITHUB, LINEAR]);

package/src/services/base.ts

@@ -0,0 +1,234 @@
+/**
+ * Base classes and interfaces for service implementations.
+ */
+
+import type { Browser, BrowserContext, Page, Response } from 'playwright';
+import { ApiCredentialStatus, ApiCredentials } from '../apiCredentials.js';
+import { EncryptedStorage } from '../encryptedStorage.js';
+import { showSpinnerPage, withTempBrowserContext } from '../playwrightUtils.js';
+
+export class LoginCancelledError extends Error {
+  constructor(message = 'Login was cancelled because the browser was closed.') {
+    super(message);
+    this.name = 'LoginCancelledError';
+  }
+}
+
+export class LoginFailedError extends Error {
+  constructor(message = 'Login failed: no credentials were extracted.') {
+    super(message);
+    this.name = 'LoginFailedError';
+  }
+}
+
+function isBrowserClosedError(error: Error): boolean {
+  const message = error.message.toLowerCase();
+  return (
+    message.includes('target closed') ||
+    message.includes('browser closed') ||
+    message.includes('browser has been closed') ||
+    message.includes('context has been closed') ||
+    message.includes('page has been closed')
+  );
+}
+
+function isTimeoutError(error: Error): boolean {
+  return error.name === 'TimeoutError';
+}
+
+/**
+ * Base interface for a service that latchkey can authenticate with.
+ */
+export interface Service {
+  readonly name: string;
+  readonly baseApiUrls: readonly string[];
+  readonly loginUrl: string;
+
+  /**
+   * Check if the given API credentials are valid for this service.
+   */
+  checkApiCredentials(apiCredentials: ApiCredentials): ApiCredentialStatus;
+
+  /**
+   * Return curl arguments for checking credentials (excluding auth headers).
+   */
+  readonly credentialCheckCurlArguments: readonly string[];
+
+  /**
+   * Get a new session for the login flow.
+   */
+  getSession(): ServiceSession;
+}
+
+/**
+ * Base class for service sessions that handle the login flow.
+ */
+export abstract class ServiceSession {
+  readonly service: Service;
+
+  constructor(service: Service) {
+    this.service = service;
+  }
+
+  /**
+   * Handle a response during the headful login phase.
+   */
+  abstract onResponse(response: Response): void;
+
+  /**
+   * Check if the login phase is complete.
+   */
+  protected abstract isLoginComplete(): boolean;
+
+  /**
+   * Finalize credentials after the headful login phase.
+   * Receives the browser and context from the login phase, which are still open.
+   */
+  protected abstract finalizeCredentials(
+    browser: Browser,
+    context: BrowserContext
+  ): Promise<ApiCredentials | null>;
+
+  /**
+   * Wait until the browser login phase is complete.
+   */
+  private async waitForLoginComplete(page: Page): Promise<void> {
+    while (!this.isLoginComplete()) {
+      await page.waitForTimeout(100);
+    }
+  }
+
+
+  /**
+   * Optionally diagnose a timeout error that occurred during credential finalization.
+   *
+   * Services can override this to inspect the page state and return a more
+   * specific error (e.g., checking for permission denied messages).
+   * If this returns an error, it will be thrown instead of the generic
+   * LoginFailedError. If it returns null, the original timeout error message is used.
+   */
+  protected diagnoseTimeoutError(
+    _context: BrowserContext,
+    _originalError: Error
+  ): Promise<Error | null> {
+    return Promise.resolve(null);
+  }
+
+  /**
+   * Perform the login flow and return the extracted credentials.
+   */
+  async login(
+    encryptedStorage: EncryptedStorage,
+    browserStatePath: string
+  ): Promise<ApiCredentials> {
+    return withTempBrowserContext(
+      encryptedStorage,
+      browserStatePath,
+      async ({ browser, context }) => {
+        const page = await context.newPage();
+
+        page.on('response', (response) => {
+          this.onResponse(response);
+        });
+
+        try {
+          await page.goto(this.service.loginUrl);
+          await this.waitForLoginComplete(page);
+        } catch (error: unknown) {
+          if (error instanceof Error && isBrowserClosedError(error)) {
+            throw new LoginCancelledError();
+          }
+          throw error;
+        }
+
+        let apiCredentials: ApiCredentials | null;
+        try {
+          apiCredentials = await this.finalizeCredentials(browser, context);
+        } catch (error: unknown) {
+          if (error instanceof Error && isBrowserClosedError(error)) {
+            throw new LoginCancelledError();
+          }
+          if (error instanceof Error && isTimeoutError(error)) {
+            const diagnosedError = await this.diagnoseTimeoutError(context, error);
+            if (diagnosedError !== null) {
+              throw diagnosedError;
+            }
+            throw new LoginFailedError(`Login failed: ${error.message}`);
+          }
+          throw error;
+        }
+
+        if (apiCredentials === null) {
+          throw new LoginFailedError();
+        }
+
+        return apiCredentials;
+      }
+    );
+  }
+}
+
+/**
+ * Simple service session where credentials are extracted by observing requests during login.
+ */
+export abstract class SimpleServiceSession extends ServiceSession {
+  protected apiCredentials: ApiCredentials | null = null;
+
+  /**
+   * Extract API credentials from a response during the headful login phase.
+   */
+  protected abstract getApiCredentialsFromResponse(
+    response: Response
+  ): Promise<ApiCredentials | null>;
+
+  onResponse(response: Response): void {
+    if (this.apiCredentials !== null) {
+      return;
+    }
+    this.getApiCredentialsFromResponse(response)
+      .then((credentials) => {
+        if (this.apiCredentials === null && credentials !== null) {
+          this.apiCredentials = credentials;
+        }
+      })
+      .catch(() => {
+        // Ignore errors extracting credentials
+      });
+  }
+
+  protected isLoginComplete(): boolean {
+    return this.apiCredentials !== null;
+  }
+
+  protected finalizeCredentials(
+    _browser: Browser,
+    _context: BrowserContext
+  ): Promise<ApiCredentials | null> {
+    return Promise.resolve(this.apiCredentials);
+  }
+}
+
+/**
+ * Service session that requires a browser followup to finalize credentials.
+ *
+ * The login phase captures login state. After login completes,
+ * the same browser session is reused to perform additional actions
+ * (e.g., navigating to settings and creating an API key).
+ */
+export abstract class BrowserFollowupServiceSession extends ServiceSession {
+  /**
+   * Perform actions in the browser to finalize and extract API credentials.
+   * This runs in the same browser session used for login.
+   */
+  protected abstract performBrowserFollowup(
+    context: BrowserContext
+  ): Promise<ApiCredentials | null>;
+
+  protected override async finalizeCredentials(
+    _browser: Browser,
+    context: BrowserContext
+  ): Promise<ApiCredentials | null> {
+    await showSpinnerPage(context, this.service.name);
+    return this.performBrowserFollowup(context);
+  }
+}

package/src/services/discord.ts

@@ -0,0 +1,73 @@
+/**
+ * Discord service implementation.
+ */
+
+import type { Response } from 'playwright';
+import { ApiCredentialStatus, ApiCredentials, AuthorizationBare } from '../apiCredentials.js';
+import { runCaptured } from '../curl.js';
+import { Service, SimpleServiceSession } from './base.js';
+
+class DiscordServiceSession extends SimpleServiceSession {
+  protected async getApiCredentialsFromResponse(
+    response: Response
+  ): Promise<ApiCredentials | null> {
+    const request = response.request();
+    const url = request.url();
+
+    if (!url.startsWith('https://discord.com/api/')) {
+      return null;
+    }
+
+    // Require 2XX response to ensure the session is valid (not expired)
+    const status = response.status();
+    if (status < 200 || status >= 300) {
+      return null;
+    }
+
+    const headers = await request.allHeaders();
+    const authorization = headers.authorization;
+    if (authorization !== undefined && authorization.trim() !== '') {
+      return new AuthorizationBare(authorization);
+    }
+
+    return null;
+  }
+}
+
+export class Discord implements Service {
+  readonly name = 'discord';
+  readonly baseApiUrls = ['https://discord.com/api/'] as const;
+  readonly loginUrl = 'https://discord.com/login';
+
+  readonly credentialCheckCurlArguments = ['https://discord.com/api/v9/users/@me'] as const;
+
+  getSession(): DiscordServiceSession {
+    return new DiscordServiceSession(this);
+  }
+
+  checkApiCredentials(apiCredentials: ApiCredentials): ApiCredentialStatus {
+    if (!(apiCredentials instanceof AuthorizationBare)) {
+      return ApiCredentialStatus.Invalid;
+    }
+
+    const result = runCaptured(
+      [
+        '-s',
+        '-o',
+        '/dev/null',
+        '-w',
+        '%{http_code}',
+        ...apiCredentials.asCurlArguments(),
+        ...this.credentialCheckCurlArguments,
+      ],
+      10
+    );
+
+    if (result.stdout === '200') {
+      return ApiCredentialStatus.Valid;
+    }
+    return ApiCredentialStatus.Invalid;
+  }
+}
+
+export const DISCORD = new Discord();

package/src/services/dropbox.ts

@@ -0,0 +1,173 @@
+/**
+ * Dropbox service implementation.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Response, BrowserContext } from 'playwright';
+import { ApiCredentialStatus, ApiCredentials, AuthorizationBearer } from '../apiCredentials.js';
+import { runCaptured } from '../curl.js';
+import { typeLikeHuman } from '../playwrightUtils.js';
+import { Service, BrowserFollowupServiceSession, LoginFailedError } from './base.js';
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+class DropboxServiceSession extends BrowserFollowupServiceSession {
+  private isLoggedIn = false;
+
+  onResponse(response: Response): void {
+    if (this.isLoggedIn) {
+      return;
+    }
+
+    const request = response.request();
+    const url = request.url();
+    if (!url.startsWith('https://www.dropbox.com/')) {
+      return;
+    }
+
+    // Require 2XX response to ensure the session is valid (not expired)
+    const status = response.status();
+    if (status < 200 || status >= 300) {
+      return;
+    }
+
+    const headers = request.headers();
+    const uidHeader = headers['x-dropbox-uid'];
+    if (uidHeader === undefined || uidHeader === '-1') {
+      return;
+    }
+
+    this.isLoggedIn = true;
+  }
+
+  protected isLoginComplete(): boolean {
+    return this.isLoggedIn;
+  }
+
+  protected async performBrowserFollowup(context: BrowserContext): Promise<ApiCredentials | null> {
+    const page = context.pages()[0];
+    if (!page) {
+      throw new LoginFailedError('No page available in browser context.');
+    }
+
+    await page.goto('https://www.dropbox.com/developers/apps/create');
+
+    const scopedInput = page.locator('input#scoped');
+    await scopedInput.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await scopedInput.click();
+
+    const fullPermissionsInput = page.locator('input#full_permissions');
+    await fullPermissionsInput.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await fullPermissionsInput.click();
+
+    const appName = `Latchkey-${randomUUID().slice(0, 8)}`;
+    const appNameInput = page.locator('input#app-name');
+    await appNameInput.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await typeLikeHuman(page, appNameInput, appName);
+
+    const createButton = page.getByRole('button', { name: 'Create app' });
+    await createButton.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await createButton.click();
+
+    await page.waitForURL(/https:\/\/www\.dropbox\.com\/developers\/apps\/info\//, {
+      timeout: DEFAULT_TIMEOUT_MS,
+    });
+
+    // Configure permissions before generating token
+    const permissionsTab = page.locator('a.c-tabs__label[data-hash="permissions"]');
+    await permissionsTab.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await permissionsTab.click();
+
+    // Enable all necessary permissions
+    const permissionIds = [
+      'files.metadata.write',
+      'files.content.write',
+      'files.content.read',
+      'sharing.write',
+      'file_requests.write',
+      'contacts.write',
+    ];
+
+    for (const permissionId of permissionIds) {
+      const escapedPermissionId = permissionId.replace(/\./g, '\\.');
+      const checkbox = page.locator(`input#${escapedPermissionId}`);
+      await checkbox.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+      await checkbox.click();
+    }
+
+    // Submit permissions
+    const submitButton = page.locator('button.permissions-submit-button');
+    await submitButton.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await submitButton.click();
+
+    // Wait for permissions to be saved
+    await page.waitForTimeout(512);
+
+    // Return to Settings tab to generate token
+    const settingsTab = page.locator('a.c-tabs__label[data-hash="settings"]');
+    await settingsTab.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await settingsTab.click();
+
+    const generateButton = page.locator('input#generate-token-button');
+    await generateButton.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+    await generateButton.click();
+
+    const tokenInput = page.locator('input#generated-token[data-token]');
+    await tokenInput.waitFor({ timeout: DEFAULT_TIMEOUT_MS });
+
+    const token = await tokenInput.getAttribute('data-token');
+    if (token === null || token === '') {
+      throw new LoginFailedError('Failed to extract token from Dropbox.');
+    }
+
+    await page.close();
+
+    return new AuthorizationBearer(token);
+  }
+}
+
+export class Dropbox implements Service {
+  readonly name = 'dropbox';
+  readonly baseApiUrls = [
+    'https://api.dropboxapi.com/',
+    'https://content.dropboxapi.com/',
+    'https://notify.dropboxapi.com/',
+  ] as const;
+  readonly loginUrl = 'https://www.dropbox.com/login';
+
+  readonly credentialCheckCurlArguments = [
+    '-X',
+    'POST',
+    'https://api.dropboxapi.com/2/users/get_current_account',
+  ] as const;
+
+  getSession(): DropboxServiceSession {
+    return new DropboxServiceSession(this);
+  }
+
+  checkApiCredentials(apiCredentials: ApiCredentials): ApiCredentialStatus {
+    if (!(apiCredentials instanceof AuthorizationBearer)) {
+      return ApiCredentialStatus.Invalid;
+    }
+
+    const result = runCaptured(
+      [
+        '-s',
+        '-o',
+        '/dev/null',
+        '-w',
+        '%{http_code}',
+        ...apiCredentials.asCurlArguments(),
+        ...this.credentialCheckCurlArguments,
+      ],
+      10
+    );
+
+    if (result.stdout === '200') {
+      return ApiCredentialStatus.Valid;
+    }
+    return ApiCredentialStatus.Invalid;
+  }
+}
+
+export const DROPBOX = new Dropbox();