latchkey 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latchkey",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A CLI tool that injects API credentials into curl requests for known third-party services",
   "author": "Imbue <hynek@imbue.com>",
   "repository": {
@@ -12,19 +12,19 @@
     "url": "https://github.com/imbue-ai/latchkey/issues"
   },
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
   "bin": {
     "latchkey": "./dist/src/cli.js"
   },
-  "scripts": {
-    "postinstall": "npx playwright install chromium",
-    "prepublishOnly": "npm run build",
-    "files": [
+  "files": [
       "dist",
       "README.md",
       "LICENSE"
-    ],
+  ],
+  "scripts": {
+    "postinstall": "npx playwright install chromium",
+    "prepublishOnly": "npm run build",
     "build": "tsc",
     "dev": "tsc --watch",
     "lint": "eslint src tests scripts",

package/.nvmrc

@@ -1 +0,0 @@
-24.13.0

package/.pre-commit-config.yaml

@@ -1,22 +0,0 @@
-default_install_hook_types: [pre-commit]
-
-repos:
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v6.0.0
-    hooks:
-    -   id: trailing-whitespace
-    -   id: end-of-file-fixer
-    -   id: check-added-large-files
-        exclude: 'uv.lock'
-    -   id: check-yaml
--   repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.22
-    hooks:
-    -   id: uv-lock
--   repo: local
-    hooks:
-    -   id: ruff
-        name: "Python formatter + import sorter (ruff)"
-        entry: bash -c 'uv run ruff check --select UP006,UP007,I,F401 --fix --force-exclude --config pyproject.toml "$@" && uv run ruff format --force-exclude --config pyproject.toml "$@"' --
-        language: system
-        types: [python]

package/.prettierignore

@@ -1,4 +0,0 @@
-dist
-node_modules
-coverage
-*.md

package/.prettierrc

@@ -1,7 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "es5",
-  "tabWidth": 2,
-  "printWidth": 100
-}

package/CLAUDE.md

@@ -1,13 +0,0 @@
-For information about the high-level goal and motivations, see README.md.
-
-You are a highly intelligent and experienced software creator that codes in a straightforward way, prefers simplicity and avoids overengineering.
-
-Typescript style guide:
-
-- Use modern Typescript code.
-- Prefer functional, stateless logic as much as possible.
-- Use immutable data structures as much as possible.
-- Do not use abbreviations in variable (class, function, ...) names. It's fine for names to be somewhat verbose.
-- Omit docstrings if they don't add any value beyond what can be obviously inferred from the function signature / class name.
-- Do not throw builtin errors; always replace them with dedicated error subclasses.
-- When done, validate your changes by running `npm lint` and `npm test`.

package/docs/development.md

@@ -1,94 +0,0 @@
-# Developing Latchkey
-
-Thank you for considering contributing to Latchkey!
-
-## Setting up your environment
-
-Make sure you're using [nvm](https://github.com/nvm-sh/nvm) so that your node version
-corresponds to the one listed in `.nvmrc`.
-
-After that, the easiest way to set up your system so that you can run
-Latchkey while working on it is to clone this repository and
-then run:
-
-```
-npm install && npm run build && npm link
-```
-
-After that, every time you make a change to the code, run
-`npm run rebuild`. Invoking `latchkey` in your terminal will
-then use the version you just built.
-
-## Before you submit a PR
-
-- Run `npm lint` and `npm test` to validate your changes.
-- Run `npm format` to apply autoformatting.
-
-
-## Adding a new service
-
-Each third-party service needs to be approached slightly
-differently. When adding support for a new service, you need to
-start by asking yourself the following question:
-
-
-_Can an API token be extracted from the network traffic that flows between the browser and the service's website during or after login?_
-
-If the answer is yes, see how the [Discord](../src/services/discord.ts) service is implemented and try to do it similarly.
-
-Otherwise, ask yourself the following question:
-
-_Can an API token be created in the user's account (e.g. in Developer settings)?_
-
-If so, see how the [Linear](../src/services/linear.ts) service is implemented and try to do it similarly.
-
-When possible, the first option (extracting the token from the
-network traffic) is always preferable because it's simpler, more
-robust, and less invasive.  If the answer is no in both cases,
-it's a special case and you're on your own!
-
-Above, when we say "API", we always mean a public API. Do
-not expose undocumented private APIs through Latchkey - agents
-should be able to determine usage by consulting the documentation.
-
-
-### Potentially useful helpers
-
-#### Request / response recorder
-
-Use this to record the request/response pairs of your browser
-login sequence as plaintext JSON files. The resulting recording
-can be inspected, either manually or with the help of AI, to see
-if you can extract an API token or something similar from there.
-
-```
-npx tsx scripts/recordBrowserSession.ts <service_name>
-```
-
-If you have `jq` installed on your system, you can then
-start exploring, for instance like this:
-
-```
-cat path/to/recording/login_session.json | jq -C | less -R
-```
-
-#### File encryptor / decryptor
-
-During development, it may sometimes be necessary to inspect the
-credentials stored in `~/.latchkey/credentials.json.enc`.
-
-To do that, you can use `scripts/cryptFile.ts`. For example:
-
-```
-npx tsx scripts/cryptFile.ts decrypt ~/.latchkey/credentials.json.enc
-```
-
-
-#### Browser automation recorder
-
-When automating the browser login follow-up, you can sometimes
-use Playwright's codegen functionality, for example:
-
-```
-npx playwright codegen --target=javascript https://login-page.example.com/
-```

package/eslint.config.js

@@ -1,30 +0,0 @@
-import eslint from "@eslint/js";
-import tseslint from "typescript-eslint";
-
-export default tseslint.config(
-  eslint.configs.recommended,
-  ...tseslint.configs.strictTypeChecked,
-  ...tseslint.configs.stylisticTypeChecked,
-  {
-    languageOptions: {
-      parserOptions: {
-        projectService: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-  },
-  {
-    ignores: ["dist/", "node_modules/", "eslint.config.js"],
-  },
-  {
-    rules: {
-      // Allow unused variables prefixed with underscore
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
-      ],
-      // Allow non-null assertions when needed
-      "@typescript-eslint/no-non-null-assertion": "off",
-    },
-  }
-);

package/integrations/SKILL.md

@@ -1,62 +0,0 @@
----
-name: latchkey
-description: Interact with third-party services (Slack, Discord, Dropbox, GitHub, Linear...) on user's behalf using their public APIs.
----
-
-# Latchkey
-
-## Instructions
-
-Latchkey is a CLI tool that automatically injects credentials into curl commands for supported public APIs. Instead of manually managing API tokens, latchkey opens a browser for login, extracts credentials from the session, and injects them into your curl requests.
-
-Use this skill when the user asks you to work with third-party services like Slack, Discord, Dropbox, Github, Linear and others on their behalf.
-
-Usage:
-
-1. **Use `latchkey curl`** instead of regular `curl` for supported services.
-2. **Look for the newest documentation of the desired public API online.**
-3. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
-4. **Use `latchkey status <service_name>`** when you notice potentially expired credentials.
-5. When the status is `invalid`, **force a new login by calling `latchkey clear <service_name>`**, then retry the curl command.
-6. **Do not force a new login if the status is `valid`** - the user might just not have the necessary permissions.
-
-
-## Examples
-
-### Make an authenticated curl request
-```bash
-latchkey curl [curl arguments]
-```
-
-### Creating a Slack channel
-```bash
-latchkey curl -X POST 'https://slack.com/api/conversations.create' \
-  -H 'Content-Type: application/json' \
-  -d '{"name":"my-channel"}'
-```
-
-(Notice that `-H 'Authorization: Bearer` is not present in the invocation.)
-
-### Getting Discord user info
-```bash
-latchkey curl 'https://discord.com/api/v10/users/@me'
-```
-
-### Clear expired credentials and force a new login to Discord
-```bash
-latchkey status discord  # Returns "invalid"
-latchkey clear discord
-latchkey curl 'https://discord.com/api/v10/users/@me'
-```
-
-Only do this when you notice that your previous call ended up not being authenticated (HTTP 401 or 403). The next `latchkey curl` call will trigger a new login flow.
-
-### List supported services
-```bash
-latchkey services
-```
-
-## Notes
-
-- All curl arguments are passed through unchanged
-- Return codes, stdin, and stdout are passed back from curl

package/scripts/cryptFile.ts

@@ -1,123 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * CLI tool for encrypting and decrypting latchkey files.
- *
- * This is a developer utility for inspecting and modifying encrypted
- * credential and browser state files.
- *
- * Usage:
- *   npx tsx scripts/cryptFile.ts decrypt <file>     # Decrypt file in place
- *   npx tsx scripts/cryptFile.ts encrypt <file>     # Encrypt file in place
- *
- * The encryption key is sourced from:
- *   1. LATCHKEY_ENCRYPTION_KEY environment variable
- *   2. System keychain
- *
- * Examples:
- *   npx tsx scripts/cryptFile.ts decrypt ~/.latchkey/credentials.json
- *   npx tsx scripts/cryptFile.ts encrypt ~/.latchkey/credentials.json
- */
-
-import { program } from 'commander';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { CONFIG } from '../src/config.js';
-import { EncryptedStorage } from '../src/encryptedStorage.js';
-import { encrypt, generateKey } from '../src/encryption.js';
-import { isKeychainAvailable, retrieveFromKeychain } from '../src/keychain.js';
-
-const ENCRYPTED_FILE_PREFIX = 'LATCHKEY_ENCRYPTED:';
-
-function getEncryptionKey(): string {
-  // 1. Check environment variable via Config
-  if (CONFIG.encryptionKeyOverride) {
-    return CONFIG.encryptionKeyOverride;
-  }
-
-  // 2. Check keychain
-  if (isKeychainAvailable(CONFIG.serviceName, CONFIG.accountName)) {
-    const keychainKey = retrieveFromKeychain(CONFIG.serviceName, CONFIG.accountName);
-    if (keychainKey) {
-      return keychainKey;
-    }
-  }
-
-  console.error(`\
-Error: No encryption key available.
-Set LATCHKEY_ENCRYPTION_KEY or ensure the system keychain has a stored key.
-
-To generate a new key:
-  export LATCHKEY_ENCRYPTION_KEY="${generateKey()}"`);
-  process.exit(1);
-}
-
-function decryptCommand(filePath: string): void {
-  if (!existsSync(filePath)) {
-    console.error(`Error: File not found: ${filePath}`);
-    process.exit(1);
-  }
-
-  const rawContent = readFileSync(filePath, 'utf-8');
-  if (!rawContent.startsWith(ENCRYPTED_FILE_PREFIX)) {
-    console.error(`Error: File is not encrypted: ${filePath}`);
-    process.exit(1);
-  }
-
-  const storage = new EncryptedStorage({
-    serviceName: CONFIG.serviceName,
-    accountName: CONFIG.accountName,
-  });
-  const content = storage.readFile(filePath);
-
-  if (content === null) {
-    console.error(`Error: Could not read file: ${filePath}`);
-    process.exit(1);
-  }
-
-  writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
-  console.error(`Decrypted: ${filePath}`);
-}
-
-function encryptCommand(filePath: string): void {
-  if (!existsSync(filePath)) {
-    console.error(`Error: File not found: ${filePath}`);
-    process.exit(1);
-  }
-
-  const content = readFileSync(filePath, 'utf-8');
-  if (content.startsWith(ENCRYPTED_FILE_PREFIX)) {
-    console.error(`Error: File is already encrypted: ${filePath}`);
-    process.exit(1);
-  }
-
-  const key = getEncryptionKey();
-  const encryptedData = encrypt(content, key);
-  const dataToWrite = ENCRYPTED_FILE_PREFIX + encryptedData;
-
-  writeFileSync(filePath, dataToWrite, { encoding: 'utf-8', mode: 0o600 });
-  console.error(`Encrypted: ${filePath}`);
-}
-
-program.name('cryptFile').description(`\
-CLI tool for encrypting and decrypting latchkey files.
-
-The encryption key is sourced from:
-  1. LATCHKEY_ENCRYPTION_KEY environment variable
-  2. System keychain`);
-
-program
-  .command('decrypt')
-  .description('Decrypt file in place')
-  .argument('<file>', 'Path to the encrypted file')
-  .action((filePath: string) => {
-    decryptCommand(filePath);
-  });
-
-program
-  .command('encrypt')
-  .description('Encrypt an unencrypted file in place')
-  .argument('<file>', 'Path to the file to encrypt')
-  .action((filePath: string) => {
-    encryptCommand(filePath);
-  });
-
-program.parse();

package/scripts/recordBrowserSession.ts

@@ -1,280 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Record browser requests and responses during a login session.
- *
- * This script opens a browser at a service's login URL and records all HTTP
- * requests and responses (including their headers and timing). When you close the
- * browser, the recording is saved. This is useful for recording login flows that
- * can be replayed later for testing credentials extraction.
- *
- * Usage:
- *   npx tsx scripts/recordBrowserSession.ts <service_name> [recording_name]
- *
- * Examples:
- *   npx tsx scripts/recordBrowserSession.ts slack
- *   npx tsx scripts/recordBrowserSession.ts discord custom_session.json
- */
-
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { Response } from 'playwright';
-import { CONFIG } from '../src/config.js';
-import { EncryptedStorage } from '../src/encryptedStorage.js';
-import { withTempBrowserContext } from '../src/playwrightUtils.js';
-import { REGISTRY } from '../src/registry.js';
-
-// Get the directory of this file
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Recordings directory relative to this script
-const RECORDINGS_DIRECTORY = resolve(__dirname, 'recordings');
-
-// Default recording filename
-const DEFAULT_RECORDING_NAME = 'login_session.json';
-
-class UnknownServiceError extends Error {
-  constructor(serviceName: string) {
-    super(`Unknown service: ${serviceName}`);
-    this.name = 'UnknownServiceError';
-  }
-}
-
-// Resource types to skip (CSS, images, fonts, multimedia)
-const SKIPPED_RESOURCE_TYPES = new Set(['stylesheet', 'image', 'media', 'font']);
-
-// Common multi-part TLDs
-const MULTI_PART_TLDS = new Set(['co.uk', 'com.au', 'co.nz', 'co.jp', 'com.br', 'co.in']);
-
-interface RequestData {
-  timestamp_ms: number;
-  method: string;
-  url: string;
-  headers: Record<string, string>;
-  resource_type: string;
-  post_data?: string;
-}
-
-interface ResponseData {
-  status: number;
-  status_text: string;
-  headers: Record<string, string>;
-  body?: string;
-}
-
-interface RecordedEntry {
-  request: RequestData;
-  response: ResponseData;
-}
-
-/**
- * Extract the base domain from a URL.
- *
- * For example:
- *   https://discord.com/login -> discord.com
- *   https://api.discord.com/v9/users -> discord.com
- *   https://www.example.co.uk/page -> example.co.uk
- */
-function extractBaseDomain(url: string): string {
-  let hostname: string;
-  try {
-    hostname = new URL(url).hostname;
-  } catch {
-    return '';
-  }
-
-  // Split the hostname into parts
-  const parts = hostname.split('.');
-
-  // Handle common multi-part TLDs (e.g., co.uk, com.au)
-  if (parts.length >= 3) {
-    const potentialTld = parts.slice(-2).join('.');
-    if (MULTI_PART_TLDS.has(potentialTld)) {
-      return parts.slice(-3).join('.');
-    }
-  }
-
-  if (parts.length >= 2) {
-    return parts.slice(-2).join('.');
-  }
-
-  return hostname;
-}
-
-/**
- * Check if a request URL belongs to the same base domain.
- */
-function isSameBaseDomain(requestUrl: string, baseDomain: string): boolean {
-  let requestHostname: string;
-  try {
-    requestHostname = new URL(requestUrl).hostname;
-  } catch {
-    return false;
-  }
-  return requestHostname === baseDomain || requestHostname.endsWith('.' + baseDomain);
-}
-
-/**
- * Handle a response and record both request and response details.
- */
-async function handleResponse(
-  response: Response,
-  recordedEntries: RecordedEntry[],
-  startTime: { value: number },
-  baseDomain: string
-): Promise<void> {
-  const request = response.request();
-
-  // Skip CSS, images, fonts, and multimedia
-  if (SKIPPED_RESOURCE_TYPES.has(request.resourceType())) {
-    return;
-  }
-
-  // Skip requests to external domains
-  if (!isSameBaseDomain(request.url(), baseDomain)) {
-    return;
-  }
-
-  if (startTime.value === 0) {
-    startTime.value = Date.now();
-  }
-
-  const timestampMs = Date.now() - startTime.value;
-
-  const requestData: RequestData = {
-    timestamp_ms: timestampMs,
-    method: request.method(),
-    url: request.url(),
-    headers: await request.allHeaders(),
-    resource_type: request.resourceType(),
-  };
-
-  // Include POST data if present
-  try {
-    const postData = request.postData();
-    if (postData !== null) {
-      requestData.post_data = postData;
-    }
-  } catch {
-    // Post data not available or not decodable
-  }
-
-  const responseData: ResponseData = {
-    status: response.status(),
-    status_text: response.statusText(),
-    headers: await response.allHeaders(),
-  };
-
-  // Try to get response body as text (skip binary content)
-  try {
-    const body = await response.text();
-    responseData.body = body;
-  } catch {
-    // Binary content or other error - skip body
-  }
-
-  recordedEntries.push({
-    request: requestData,
-    response: responseData,
-  });
-}
-
-/**
- * Record browser requests and responses during a login session.
- */
-async function record(
-  serviceName: string,
-  recordingName: string = DEFAULT_RECORDING_NAME
-): Promise<void> {
-  const service = REGISTRY.getByName(serviceName);
-  if (service === null) {
-    throw new UnknownServiceError(serviceName);
-  }
-
-  const outputDirectory = join(RECORDINGS_DIRECTORY, serviceName);
-  mkdirSync(outputDirectory, { recursive: true });
-  const requestsPath = join(outputDirectory, recordingName);
-
-  const browserStatePath = CONFIG.browserStatePath;
-
-  const baseDomain = extractBaseDomain(service.loginUrl);
-
-  console.log(`Recording login for service: ${service.name}`);
-  console.log(`Login URL: ${service.loginUrl}`);
-  console.log(`Recording requests to: ${baseDomain} (and subdomains)`);
-  console.log(`Output directory: ${outputDirectory}`);
-  console.log(`Browser state: ${browserStatePath}`);
-  console.log("\nClose the browser window when you're done to save the recording.");
-
-  const recordedEntries: RecordedEntry[] = [];
-  const startTime = { value: 0 };
-
-  const encryptedStorage = new EncryptedStorage({
-    encryptionKeyOverride: CONFIG.encryptionKeyOverride,
-    serviceName: CONFIG.serviceName,
-    accountName: CONFIG.accountName,
-  });
-
-  await withTempBrowserContext(encryptedStorage, browserStatePath, async ({ context }) => {
-    const page = await context.newPage();
-
-    // Register response handler to capture all requests and responses
-    page.on('response', (response) => {
-      handleResponse(response, recordedEntries, startTime, baseDomain).catch(() => {
-        // Ignore errors in response handling
-      });
-    });
-
-    await page.goto(service.loginUrl);
-
-    // Wait for user to close the browser
-    await page.waitForEvent('close', { timeout: 0 });
-  });
-
-  // Save recorded entries
-  writeFileSync(requestsPath, JSON.stringify(recordedEntries, null, 2));
-
-  console.log('\nRecording saved successfully!');
-  console.log(`  Requests file: ${requestsPath}`);
-  console.log(`  Recorded ${String(recordedEntries.length)} request/response pairs`);
-}
-
-// Main entry point
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log('Usage: npx tsx scripts/recordBrowserSession.ts <service_name> [recording_name]');
-    console.log('');
-    console.log('Arguments:');
-    console.log(
-      "  service_name    Name of the service to record login for (e.g., 'slack', 'discord')"
-    );
-    console.log('  recording_name  Name of the recording file (default: login_session.json)');
-    console.log('');
-    console.log('Examples:');
-    console.log('  npx tsx scripts/recordBrowserSession.ts slack');
-    console.log('  npx tsx scripts/recordBrowserSession.ts discord custom_session.json');
-    process.exit(0);
-  }
-
-  const serviceName = args[0]!;
-  const recordingName = args[1] ?? DEFAULT_RECORDING_NAME;
-
-  try {
-    await record(serviceName, recordingName);
-  } catch (error) {
-    if (error instanceof UnknownServiceError) {
-      console.error(`Error: ${error.message}`);
-      console.error('Available services:');
-      for (const service of REGISTRY.services) {
-        console.error(`  - ${service.name}`);
-      }
-      process.exit(1);
-    }
-    throw error;
-  }
-}
-
-void main();

package/scripts/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "..",
-    "outDir": "../dist/scripts",
-    "noEmit": true
-  },
-  "include": ["./**/*", "../src/**/*"],
-  "exclude": ["../node_modules", "../dist"]
-}