@openparachute/vault 0.1.0

package/src/triggers.ts

@@ -0,0 +1,412 @@
+/**
+ * Generic webhook trigger system.
+ *
+ * Replaces the hardcoded tts-hook and transcription-hook with a declarative
+ * config-driven approach. Each trigger defines a predicate (tags, content,
+ * metadata) and an action (webhook URL + send/response modes). When a note
+ * mutation matches, the trigger fires a webhook and applies the response.
+ *
+ * ## Two-phase marker discipline (inherited from the old hooks)
+ *
+ *   1. On entry: write `metadata.<trigger_name>_pending_at = <now>`.
+ *      The predicate checks `missing_metadata` which includes the pending
+ *      and rendered markers, so a concurrent update cannot start a second run.
+ *   2. On success: replace `_pending_at` with `_rendered_at` and apply the
+ *      webhook response (content, metadata, attachments).
+ *   3. On failure: leave `_pending_at` set. Manual recovery required.
+ *
+ * ## Send modes
+ *
+ *   - `json` (default): POST `{ trigger, event, note }` as JSON.
+ *     Response: `{ content?, metadata?, attachments? }`.
+ *   - `attachment`: Read the first audio attachment, POST as multipart/form-data.
+ *     Response: `{ text }` (Whisper API shape). Written to note.content.
+ *   - `content`: POST `{ input: note.content }` as JSON (OpenAI TTS shape).
+ *     Response: binary audio bytes. Saved to assets + attachment.
+ */
+
+import { join, normalize } from "path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+import crypto from "node:crypto";
+import type { Note, Store, Attachment } from "../core/src/types.ts";
+import type { HookRegistry, HookEvent } from "../core/src/hooks.ts";
+import type { TriggerConfig, TriggerWhen } from "./config.ts";
+import { getVaultNameForStore } from "./vault-store.ts";
+import { assetsDir } from "./routes.ts";
+
+const DEFAULT_TIMEOUT = 60_000;
+
+export interface WebhookResponse {
+  content?: string;
+  metadata?: Record<string, unknown>;
+  attachments?: Array<{
+    path: string;
+    mimeType: string;
+    meta?: Record<string, unknown>;
+  }>;
+  /** If set, the trigger is considered skipped (not failed). */
+  skipped_reason?: string;
+}
+
+/**
+ * Build a HookRegistry predicate from a TriggerWhen config.
+ */
+export function buildPredicate(when: TriggerWhen, triggerName: string): (note: Note) => boolean {
+  const pendingKey = `${triggerName}_pending_at`;
+  const renderedKey = `${triggerName}_rendered_at`;
+
+  return (note: Note) => {
+    const meta = note.metadata as Record<string, unknown> | undefined;
+
+    // Always check our own markers (two-phase discipline)
+    if (meta?.[pendingKey] || meta?.[renderedKey]) return false;
+
+    // Tag filter
+    if (when.tags?.length) {
+      if (!when.tags.every((t) => note.tags?.includes(t))) return false;
+    }
+
+    // Content filter
+    if (when.has_content === true) {
+      if (!note.content || !note.content.trim()) return false;
+    }
+    if (when.has_content === false) {
+      if (note.content && note.content.trim().length > 0) return false;
+    }
+
+    // Missing metadata filter
+    if (when.missing_metadata?.length) {
+      for (const key of when.missing_metadata) {
+        if (meta?.[key] != null) return false;
+      }
+    }
+
+    // Has metadata filter
+    if (when.has_metadata?.length) {
+      for (const key of when.has_metadata) {
+        if (meta?.[key] == null) return false;
+      }
+    }
+
+    return true;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch helpers — one per send mode
+// ---------------------------------------------------------------------------
+
+const AUDIO_MIME_TYPES = new Set(["audio/wav", "audio/mpeg", "audio/mp4", "audio/ogg", "audio/webm"]);
+
+/** Resolve the assets directory for a store. */
+function resolveAssetsDir(store: Store): string {
+  const vaultName = getVaultNameForStore(store as never);
+  return assetsDir(vaultName ?? "default");
+}
+
+/** Find the first audio attachment for a note and return its absolute path. */
+function findAudioAttachment(
+  attachments: Attachment[],
+  assetsRoot: string,
+): { attachment: Attachment; filePath: string } | null {
+  for (const att of attachments) {
+    if (!AUDIO_MIME_TYPES.has(att.mimeType)) continue;
+    const filePath = normalize(join(assetsRoot, att.path));
+    if (filePath.startsWith(normalize(assetsRoot)) && existsSync(filePath)) {
+      return { attachment: att, filePath };
+    }
+  }
+  return null;
+}
+
+/** Save binary audio to the assets dir, return relative path + MIME. */
+function saveAudioToAssets(
+  assetsRoot: string,
+  audio: Buffer,
+  contentType: string,
+): { relativePath: string; mimeType: string } {
+  const ext = contentType.includes("ogg") ? ".ogg"
+    : contentType.includes("mpeg") ? ".mp3"
+    : contentType.includes("wav") ? ".wav"
+    : contentType.includes("mp4") ? ".m4a"
+    : ".ogg"; // default to ogg
+
+  const date = new Date().toISOString().split("T")[0];
+  const dir = join(assetsRoot, date);
+  mkdirSync(dir, { recursive: true });
+
+  const filename = `${Date.now()}-${crypto.randomUUID()}${ext}`;
+  const filePath = join(dir, filename);
+  writeFileSync(filePath, audio);
+
+  return {
+    relativePath: `${date}/${filename}`,
+    mimeType: contentType || "audio/ogg",
+  };
+}
+
+interface DispatchResult {
+  webhookResult: WebhookResponse;
+}
+
+/** send=json (default): POST the note as JSON, expect standard webhook response. */
+async function dispatchJson(
+  url: string,
+  trigger: TriggerConfig,
+  note: Note,
+  attachments: Attachment[],
+  existingMeta: Record<string, unknown>,
+  hookEvent: HookEvent | undefined,
+  signal: AbortSignal,
+): Promise<DispatchResult> {
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      trigger: trigger.name,
+      event: hookEvent ?? "updated",
+      note: {
+        id: note.id,
+        content: note.content,
+        path: note.path,
+        tags: note.tags,
+        metadata: existingMeta,
+        attachments,
+        createdAt: note.createdAt,
+        updatedAt: note.updatedAt,
+      },
+    }),
+    signal,
+  });
+
+  if (!resp.ok) {
+    throw new Error(`webhook returned ${resp.status}: ${await resp.text().catch(() => "")}`);
+  }
+
+  const text = await resp.text();
+  return { webhookResult: text ? JSON.parse(text) : {} };
+}
+
+/**
+ * send=attachment: Read the first audio attachment from the vault assets dir,
+ * POST it as multipart/form-data. Expects `{ text }` response (Whisper shape).
+ */
+async function dispatchAttachment(
+  url: string,
+  note: Note,
+  attachments: Attachment[],
+  store: Store,
+  signal: AbortSignal,
+): Promise<DispatchResult> {
+  const assetsRoot = resolveAssetsDir(store);
+  const audio = findAudioAttachment(attachments, assetsRoot);
+  if (!audio) {
+    return { webhookResult: { skipped_reason: "no audio attachment found" } };
+  }
+
+  const fileBuffer = readFileSync(audio.filePath);
+  const filename = audio.attachment.path.split("/").pop() ?? "audio";
+  const file = new File([fileBuffer], filename, { type: audio.attachment.mimeType });
+
+  const form = new FormData();
+  form.append("file", file);
+
+  const resp = await fetch(url, { method: "POST", body: form, signal });
+  if (!resp.ok) {
+    throw new Error(`webhook returned ${resp.status}: ${await resp.text().catch(() => "")}`);
+  }
+
+  const result = await resp.json() as { text?: string };
+  const webhookResult: WebhookResponse = {};
+  if (result.text) {
+    webhookResult.content = result.text;
+  }
+  return { webhookResult };
+}
+
+/**
+ * send=content: POST `{ input: note.content, model?, voice? }` as JSON
+ * (OpenAI TTS shape). Response is binary audio bytes. Saved as attachment.
+ */
+async function dispatchContent(
+  url: string,
+  note: Note,
+  store: Store,
+  signal: AbortSignal,
+): Promise<DispatchResult> {
+  if (!note.content || !note.content.trim()) {
+    return { webhookResult: { skipped_reason: "note has no content to synthesize" } };
+  }
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ input: note.content }),
+    signal,
+  });
+
+  if (!resp.ok) {
+    throw new Error(`webhook returned ${resp.status}: ${await resp.text().catch(() => "")}`);
+  }
+
+  const contentType = resp.headers.get("Content-Type") ?? "audio/ogg";
+  const audioBuffer = Buffer.from(await resp.arrayBuffer());
+  const assetsRoot = resolveAssetsDir(store);
+  const { relativePath, mimeType } = saveAudioToAssets(assetsRoot, audioBuffer, contentType);
+
+  const webhookResult: WebhookResponse = {
+    attachments: [{ path: relativePath, mimeType }],
+    metadata: {
+      ...(resp.headers.get("X-TTS-Provider") ? { tts_provider: resp.headers.get("X-TTS-Provider") } : {}),
+      ...(resp.headers.get("X-TTS-Voice") ? { tts_voice: resp.headers.get("X-TTS-Voice") } : {}),
+    },
+  };
+  return { webhookResult };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all triggers from config onto a HookRegistry.
+ * Returns a cleanup function that unregisters all hooks.
+ */
+export function registerTriggers(
+  hooks: HookRegistry,
+  triggers: TriggerConfig[],
+  logger: { error: (...args: unknown[]) => void; info?: (...args: unknown[]) => void } = console,
+): () => void {
+  const unregisters: Array<() => void> = [];
+
+  for (const trigger of triggers) {
+    // Validate webhook URL at registration time so typos fail fast
+    try {
+      const url = new URL(trigger.action.webhook);
+      if (url.protocol !== "http:" && url.protocol !== "https:") {
+        logger.error(`[triggers] skipping "${trigger.name}": webhook URL must use http or https (got ${url.protocol})`);
+        continue;
+      }
+    } catch {
+      logger.error(`[triggers] skipping "${trigger.name}": invalid webhook URL "${trigger.action.webhook}"`);
+      continue;
+    }
+
+    const predicate = buildPredicate(trigger.when, trigger.name);
+    const events = trigger.events ?? ["created", "updated"];
+    const pendingKey = `${trigger.name}_pending_at`;
+    const renderedKey = `${trigger.name}_rendered_at`;
+    const timeout = trigger.action.timeout ?? DEFAULT_TIMEOUT;
+    const sendMode = trigger.action.send ?? "json";
+
+    const unregister = hooks.onNote({
+      name: trigger.name,
+      event: events,
+      when: predicate,
+      handler: async (note: Note, store: Store, hookEvent?: HookEvent) => {
+        const existingMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+
+        // Handler-side re-check (same race-window protection as the old hooks)
+        if (existingMeta[pendingKey] || existingMeta[renderedKey]) return;
+
+        const pendingAt = new Date().toISOString();
+
+        // Phase 1: claim
+        try {
+          store.updateNote(note.id, {
+            metadata: { ...existingMeta, [pendingKey]: pendingAt },
+            skipUpdatedAt: true,
+          });
+        } catch (err) {
+          logger.error(`[trigger:${trigger.name}] failed to claim note ${note.id}:`, err);
+          throw err;
+        }
+
+        // Fire the webhook using the configured send mode
+        let webhookResult: WebhookResponse;
+        const attachments = store.getAttachments(note.id);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        try {
+          let result: DispatchResult;
+          switch (sendMode) {
+            case "attachment":
+              result = await dispatchAttachment(trigger.action.webhook, note, attachments, store, controller.signal);
+              break;
+            case "content":
+              result = await dispatchContent(trigger.action.webhook, note, store, controller.signal);
+              break;
+            case "json":
+            default:
+              result = await dispatchJson(trigger.action.webhook, trigger, note, attachments, existingMeta, hookEvent, controller.signal);
+              break;
+          }
+          webhookResult = result.webhookResult;
+        } catch (err) {
+          logger.error(
+            `[trigger:${trigger.name}] webhook failed for note ${note.id}; note left in ${pendingKey} state (manual recovery required):`,
+            err,
+          );
+          throw err;
+        } finally {
+          clearTimeout(timer);
+        }
+
+        // Handle skipped result. We write `_rendered_at` even for skips so the
+        // predicate won't re-fire on future note edits — a permanently-skippable
+        // note (e.g. code-only content with no speakable text) would otherwise
+        // trigger an infinite webhook loop on every update.
+        if (webhookResult.skipped_reason) {
+          try {
+            store.updateNote(note.id, {
+              metadata: {
+                ...existingMeta,
+                [pendingKey]: undefined,
+                [renderedKey]: new Date().toISOString(),
+                [`${trigger.name}_skipped_reason`]: webhookResult.skipped_reason,
+              },
+              skipUpdatedAt: true,
+            });
+          } catch (err) {
+            logger.error(`[trigger:${trigger.name}] failed to mark note ${note.id} as skipped:`, err);
+          }
+          return;
+        }
+
+        // Phase 2: apply webhook response and mark as rendered
+        try {
+          // Add attachments first
+          if (webhookResult.attachments?.length) {
+            for (const att of webhookResult.attachments) {
+              store.addAttachment(note.id, att.path, att.mimeType, att.meta);
+            }
+          }
+
+          // Read fresh metadata to avoid clobbering concurrent edits
+          const fresh = store.getNote(note.id);
+          const freshMeta = (fresh?.metadata as Record<string, unknown> | undefined) ?? existingMeta;
+          const { [pendingKey]: _drop, ...restMeta } = freshMeta;
+
+          store.updateNote(note.id, {
+            ...(webhookResult.content !== undefined ? { content: webhookResult.content } : {}),
+            metadata: {
+              ...restMeta,
+              ...(webhookResult.metadata ?? {}),
+              [renderedKey]: new Date().toISOString(),
+            },
+            skipUpdatedAt: true,
+          });
+        } catch (err) {
+          logger.error(`[trigger:${trigger.name}] failed to apply webhook result for note ${note.id}:`, err);
+          throw err;
+        }
+      },
+    });
+
+    unregisters.push(unregister);
+    const modeStr = sendMode !== "json" ? ` (send=${sendMode})` : "";
+    logger.info?.(`[triggers] registered: ${trigger.name} → ${trigger.action.webhook}${modeStr}`);
+  }
+
+  return () => unregisters.forEach((fn) => fn());
+}

package/src/two-factor.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Tests for TOTP 2FA + backup codes (src/two-factor.ts).
+ *
+ * Uses PARACHUTE_HOME override so enrollment/regeneration touches a tmp dir
+ * instead of the user's real ~/.parachute. Must set env BEFORE importing
+ * config-dependent modules.
+ */
+
+import { describe, test, expect, beforeEach, afterAll } from "bun:test";
+import { rmSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import * as OTPAuth from "otpauth";
+
+const testDir = join(tmpdir(), `vault-2fa-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+process.env.PARACHUTE_HOME = testDir;
+
+const {
+  enrollTotp,
+  disableTotp,
+  hasTotpEnrolled,
+  verifyTotpCode,
+  regenerateBackupCodes,
+  getBackupCodeCount,
+  verifyAndConsumeBackupCode,
+  getTotpSecret,
+  _resetTotpReplayCache,
+} = await import("./two-factor.ts");
+
+const { readGlobalConfig, writeGlobalConfig } = await import("./config.ts");
+
+beforeEach(() => {
+  // Fresh per-test state
+  if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
+  mkdirSync(testDir, { recursive: true });
+  writeGlobalConfig({ port: 1940 });
+  _resetTotpReplayCache();
+});
+
+afterAll(() => {
+  if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// TOTP
+// ---------------------------------------------------------------------------
+
+describe("TOTP verification", () => {
+  test("accepts the current code", () => {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    const totp = new OTPAuth.TOTP({
+      issuer: "Parachute Vault",
+      label: "owner",
+      algorithm: "SHA1",
+      digits: 6,
+      period: 30,
+      secret: OTPAuth.Secret.fromBase32(secret),
+    });
+    const code = totp.generate();
+    expect(verifyTotpCode(secret, code)).toBe(true);
+  });
+
+  test("accepts prev/next window (±30s drift)", () => {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    const totp = new OTPAuth.TOTP({
+      issuer: "Parachute Vault",
+      label: "owner",
+      algorithm: "SHA1",
+      digits: 6,
+      period: 30,
+      secret: OTPAuth.Secret.fromBase32(secret),
+    });
+    const now = Date.now();
+    const prev = totp.generate({ timestamp: now - 30_000 });
+    const next = totp.generate({ timestamp: now + 30_000 });
+    expect(verifyTotpCode(secret, prev)).toBe(true);
+    expect(verifyTotpCode(secret, next)).toBe(true);
+  });
+
+  test("rejects a code from 2 windows away", () => {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    const totp = new OTPAuth.TOTP({
+      issuer: "Parachute Vault",
+      label: "owner",
+      algorithm: "SHA1",
+      digits: 6,
+      period: 30,
+      secret: OTPAuth.Secret.fromBase32(secret),
+    });
+    const farCode = totp.generate({ timestamp: Date.now() - 120_000 });
+    expect(verifyTotpCode(secret, farCode)).toBe(false);
+  });
+
+  test("rejects replay of the same code within its window", () => {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    const totp = new OTPAuth.TOTP({
+      issuer: "Parachute Vault",
+      label: "owner",
+      algorithm: "SHA1",
+      digits: 6,
+      period: 30,
+      secret: OTPAuth.Secret.fromBase32(secret),
+    });
+    const code = totp.generate();
+    expect(verifyTotpCode(secret, code)).toBe(true);
+    // Same code in same window — rejected
+    expect(verifyTotpCode(secret, code)).toBe(false);
+  });
+
+  test("markUsed=false leaves the code available for re-verification", () => {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    const totp = new OTPAuth.TOTP({
+      issuer: "Parachute Vault",
+      label: "owner",
+      algorithm: "SHA1",
+      digits: 6,
+      period: 30,
+      secret: OTPAuth.Secret.fromBase32(secret),
+    });
+    const code = totp.generate();
+    expect(verifyTotpCode(secret, code, false)).toBe(true);
+    expect(verifyTotpCode(secret, code, false)).toBe(true);
+    // But once markUsed is the default, it's consumed.
+    expect(verifyTotpCode(secret, code)).toBe(true);
+    expect(verifyTotpCode(secret, code)).toBe(false);
+  });
+
+  test("rejects malformed codes", () => {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    expect(verifyTotpCode(secret, "abc123")).toBe(false);
+    expect(verifyTotpCode(secret, "12345")).toBe(false);
+    expect(verifyTotpCode(secret, "1234567")).toBe(false);
+    expect(verifyTotpCode(secret, "")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enrollment
+// ---------------------------------------------------------------------------
+
+describe("enrollment lifecycle", () => {
+  test("enroll generates secret + 6 backup codes and persists them", async () => {
+    expect(hasTotpEnrolled()).toBe(false);
+    const result = await enrollTotp();
+
+    expect(result.secret).toMatch(/^[A-Z2-7]+$/);
+    expect(result.otpauthUrl).toStartWith("otpauth://totp/");
+    expect(result.backupCodes).toHaveLength(6);
+    expect(new Set(result.backupCodes).size).toBe(6); // unique
+    for (const c of result.backupCodes) {
+      expect(c).toMatch(/^[a-z2-9]{8}$/);
+    }
+
+    expect(hasTotpEnrolled()).toBe(true);
+    expect(getTotpSecret()).toBe(result.secret);
+    expect(getBackupCodeCount()).toBe(6);
+  });
+
+  test("enroll is round-trippable via config reload", async () => {
+    const result = await enrollTotp();
+    // Force-reload from disk
+    const fresh = readGlobalConfig();
+    expect(fresh.totp_secret).toBe(result.secret);
+    expect(fresh.backup_codes).toHaveLength(6);
+  });
+
+  test("disable removes secret and backup codes", async () => {
+    await enrollTotp();
+    disableTotp();
+    expect(hasTotpEnrolled()).toBe(false);
+    expect(getTotpSecret()).toBeNull();
+    expect(getBackupCodeCount()).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Backup codes
+// ---------------------------------------------------------------------------
+
+describe("backup codes", () => {
+  test("valid code verifies and is consumed", async () => {
+    const result = await enrollTotp();
+    const code = result.backupCodes[0];
+
+    expect(await verifyAndConsumeBackupCode(code)).toBe(true);
+    expect(getBackupCodeCount()).toBe(5);
+    // Second use fails
+    expect(await verifyAndConsumeBackupCode(code)).toBe(false);
+    expect(getBackupCodeCount()).toBe(5);
+  });
+
+  test("invalid code does not consume any", async () => {
+    await enrollTotp();
+    expect(await verifyAndConsumeBackupCode("nope1234")).toBe(false);
+    expect(getBackupCodeCount()).toBe(6);
+  });
+
+  test("case-insensitive / whitespace-tolerant", async () => {
+    const result = await enrollTotp();
+    const code = result.backupCodes[2];
+    // Uppercase with spaces
+    expect(await verifyAndConsumeBackupCode(`  ${code.toUpperCase()}  `)).toBe(true);
+  });
+
+  test("regenerate invalidates old codes", async () => {
+    const result = await enrollTotp();
+    const oldCode = result.backupCodes[0];
+    const newCodes = await regenerateBackupCodes();
+    expect(newCodes).toHaveLength(6);
+    expect(getBackupCodeCount()).toBe(6);
+    expect(await verifyAndConsumeBackupCode(oldCode)).toBe(false);
+    expect(await verifyAndConsumeBackupCode(newCodes[0])).toBe(true);
+  });
+
+  test("concurrent consumption of the same code — only one wins", async () => {
+    const result = await enrollTotp();
+    const code = result.backupCodes[0];
+    // Kick off two verify calls in parallel; serialization via the mutex
+    // should prevent both from succeeding.
+    const [a, b] = await Promise.all([
+      verifyAndConsumeBackupCode(code),
+      verifyAndConsumeBackupCode(code),
+    ]);
+    expect([a, b].filter(Boolean).length).toBe(1);
+    expect(getBackupCodeCount()).toBe(5);
+  });
+
+  test("concurrent consumption of distinct codes — both win", async () => {
+    const result = await enrollTotp();
+    const [a, b] = await Promise.all([
+      verifyAndConsumeBackupCode(result.backupCodes[0]),
+      verifyAndConsumeBackupCode(result.backupCodes[1]),
+    ]);
+    expect(a).toBe(true);
+    expect(b).toBe(true);
+    expect(getBackupCodeCount()).toBe(4);
+  });
+
+  test("all codes consumable exactly once", async () => {
+    const result = await enrollTotp();
+    for (const code of result.backupCodes) {
+      expect(await verifyAndConsumeBackupCode(code)).toBe(true);
+    }
+    expect(getBackupCodeCount()).toBe(0);
+  });
+});