@openparachute/vault 0.1.0 → 0.2.0

package/core/src/notes.ts

@@ -72,10 +72,45 @@ export function getNotes(db: Database, ids: string[]): Note[] {
   });
 }
 
+/**
+ * Thrown by `updateNote` when an `if_updated_at` precondition does not match
+ * the note's current `updated_at`. The SELECT+check+UPDATE happens as one
+ * atomic conditional UPDATE so two concurrent callers cannot both pass the
+ * check and both commit.
+ */
+export class ConflictError extends Error {
+  code = "CONFLICT" as const;
+  note_id: string;
+  current_updated_at: string | null;
+  expected_updated_at: string;
+
+  constructor(noteId: string, current: string | null, expected: string) {
+    super(
+      `conflict: note "${noteId}" has been modified (current updated_at=${current ?? "null"}, expected=${expected})`,
+    );
+    this.name = "ConflictError";
+    this.note_id = noteId;
+    this.current_updated_at = current;
+    this.expected_updated_at = expected;
+  }
+}
+
 export function updateNote(
   db: Database,
   id: string,
-  updates: { content?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean },
+  updates: {
+    content?: string;
+    path?: string;
+    metadata?: Record<string, unknown>;
+    created_at?: string;
+    skipUpdatedAt?: boolean;
+    /**
+     * Optimistic concurrency token. When provided, the UPDATE runs with an
+     * additional `AND updated_at IS ?` clause; if no row is affected and the
+     * note still exists, a `ConflictError` is thrown.
+     */
+    if_updated_at?: string;
+  },
 ): Note {
   const sets: string[] = [];
   const values: unknown[] = [];
@@ -83,8 +118,19 @@ export function updateNote(
   // Hooks and other machine-level writers pass `skipUpdatedAt: true` so
   // their metadata markers don't look like user activity. See issue #44.
   if (!updates.skipUpdatedAt) {
+    let now = new Date().toISOString();
+    // OC contract: the new updated_at must be strictly greater than the
+    // caller's if_updated_at so a subsequent OC reader can distinguish
+    // pre- from post-update state. Without this, two writes landing in the
+    // same wall-clock millisecond would produce identical timestamps and
+    // let a second OC writer see the first writer's work as "unchanged."
+    // Comparison is lexicographic on ISO 8601 strings — valid because
+    // `.toISOString()` always emits fixed-width UTC (`...Z`).
+    if (updates.if_updated_at !== undefined && now <= updates.if_updated_at) {
+      now = new Date(new Date(updates.if_updated_at).getTime() + 1).toISOString();
+    }
     sets.push("updated_at = ?");
-    values.push(new Date().toISOString());
+    values.push(now);
   }
 
   if (updates.content !== undefined) {
@@ -104,17 +150,49 @@ export function updateNote(
     values.push(updates.created_at);
   }
 
-  // No-op: skipUpdatedAt with no other fields. Avoid generating invalid SQL.
+  // No-op: no SET fields. If a caller still passed `if_updated_at`, we
+  // need to validate the precondition; a conditional UPDATE that sets
+  // updated_at to itself does exactly that atomically — even a no-net-
+  // change UPDATE takes the write lock in WAL mode, so it still serializes
+  // with other writers and `.changes` reflects whether the WHERE matched.
   if (sets.length === 0) {
+    if (updates.if_updated_at !== undefined) {
+      const probe = db.prepare(
+        "UPDATE notes SET updated_at = updated_at WHERE id = ? AND updated_at IS ?",
+      ).run(id, updates.if_updated_at);
+      if (probe.changes === 0) {
+        throwConflictOrMissing(db, id, updates.if_updated_at);
+      }
+    }
     return getNote(db, id)!;
   }
 
   values.push(id);
-  db.prepare(`UPDATE notes SET ${sets.join(", ")} WHERE id = ?`).run(...values);
+  let sql = `UPDATE notes SET ${sets.join(", ")} WHERE id = ?`;
+  if (updates.if_updated_at !== undefined) {
+    sql += " AND updated_at IS ?";
+    values.push(updates.if_updated_at);
+  }
+
+  const res = db.prepare(sql).run(...values);
+
+  if (updates.if_updated_at !== undefined && res.changes === 0) {
+    throwConflictOrMissing(db, id, updates.if_updated_at);
+  }
 
   return getNote(db, id)!;
 }
 
+function throwConflictOrMissing(db: Database, id: string, expected: string): never {
+  const row = db.prepare("SELECT updated_at FROM notes WHERE id = ?").get(id) as
+    | { updated_at: string | null }
+    | undefined;
+  if (!row) {
+    throw new Error(`Note not found: "${id}"`);
+  }
+  throw new ConflictError(id, row.updated_at, expected);
+}
+
 export function deleteNote(db: Database, id: string): void {
   db.prepare("DELETE FROM notes WHERE id = ?").run(id);
 }

package/core/src/obsidian.test.ts

@@ -315,7 +315,7 @@ describe("exportFilePath", () => {
 // Round-trip: import → export
 // ---------------------------------------------------------------------------
 
-describe("round-trip", () => {
+describe("round-trip", async () => {
   const tmpBase = join(tmpdir(), "parachute-test-roundtrip");
   let store: SqliteStore;
 
@@ -325,7 +325,7 @@ describe("round-trip", () => {
     store = new SqliteStore(new Database(":memory:"));
   });
 
-  it("preserves content through import → vault → export", () => {
+  it("preserves content through import → vault → export", async () => {
     // Create source files
     writeFileSync(join(tmpBase, "Note.md"), `---
 tags: [daily]
@@ -338,10 +338,10 @@ Hello world.`);
     expect(notes).toHaveLength(1);
 
     // Import into vault
-    const note = store.createNote(notes[0].content, {
-      path: notes[0].path,
-      tags: notes[0].tags,
-      metadata: notes[0].frontmatter,
+    const note = await store.createNote(notes[0]!.content, {
+      path: notes[0]!.path,
+      tags: notes[0]!.tags,
+      metadata: notes[0]!.frontmatter,
     });
 
     expect(note.content).toBe("Hello world.");
@@ -357,7 +357,7 @@ Hello world.`);
     expect(md).toContain("Hello world.");
   });
 
-  it("resolves wikilinks during import", () => {
+  it("resolves wikilinks during import", async () => {
     writeFileSync(join(tmpBase, "A.md"), "See [[B]] for details.");
     writeFileSync(join(tmpBase, "B.md"), "I am note B.");
 
@@ -365,16 +365,16 @@ Hello world.`);
 
     // Import all notes
     for (const n of notes) {
-      store.createNote(n.content, {
+      await store.createNote(n.content, {
         path: n.path,
         tags: n.tags.length > 0 ? n.tags : undefined,
       });
     }
 
     // Check that A links to B
-    const noteA = store.getNoteByPath("A")!;
-    const noteB = store.getNoteByPath("B")!;
-    const links = store.getLinks(noteA.id, { direction: "outbound" });
+    const noteA = (await store.getNoteByPath("A"))!;
+    const noteB = (await store.getNoteByPath("B"))!;
+    const links = await store.getLinks(noteA.id, { direction: "outbound" });
     expect(links.some((l) => l.targetId === noteB.id && l.relationship === "wikilink")).toBe(true);
   });
 });

package/core/src/paths.test.ts

@@ -76,37 +76,37 @@ describe("hasInvalidChars", () => {
 // Path uniqueness
 // ---------------------------------------------------------------------------
 
-describe("path uniqueness", () => {
+describe("path uniqueness", async () => {
   let store: SqliteStore;
 
   beforeEach(() => {
     store = new SqliteStore(new Database(":memory:"));
   });
 
-  it("allows multiple notes without paths", () => {
-    store.createNote("A");
-    store.createNote("B");
+  it("allows multiple notes without paths", async () => {
+    await store.createNote("A");
+    await store.createNote("B");
     // Both should exist
-    const notes = store.queryNotes({ limit: 10 });
+    const notes = await store.queryNotes({ limit: 10 });
     expect(notes).toHaveLength(2);
   });
 
-  it("rejects duplicate paths", () => {
-    store.createNote("A", { path: "My Note" });
-    expect(() => store.createNote("B", { path: "My Note" })).toThrow();
+  it("rejects duplicate paths", async () => {
+    await store.createNote("A", { path: "My Note" });
+    expect(async () => await store.createNote("B", { path: "My Note" })).toThrow();
   });
 
-  it("normalizes before checking uniqueness", () => {
-    store.createNote("A", { path: "My Note.md" });
+  it("normalizes before checking uniqueness", async () => {
+    await store.createNote("A", { path: "My Note.md" });
     // "My Note.md" normalizes to "My Note" — should conflict
-    expect(() => store.createNote("B", { path: "My Note" })).toThrow();
+    expect(async () => await store.createNote("B", { path: "My Note" })).toThrow();
   });
 
-  it("allows different paths", () => {
-    store.createNote("A", { path: "Note A" });
-    store.createNote("B", { path: "Note B" });
-    expect(store.getNoteByPath("Note A")).toBeTruthy();
-    expect(store.getNoteByPath("Note B")).toBeTruthy();
+  it("allows different paths", async () => {
+    await store.createNote("A", { path: "Note A" });
+    await store.createNote("B", { path: "Note B" });
+    expect(await store.getNoteByPath("Note A")).toBeTruthy();
+    expect(await store.getNoteByPath("Note B")).toBeTruthy();
   });
 });
 
@@ -114,21 +114,21 @@ describe("path uniqueness", () => {
 // Path normalization in store operations
 // ---------------------------------------------------------------------------
 
-describe("path normalization in store", () => {
+describe("path normalization in store", async () => {
   let store: SqliteStore;
 
   beforeEach(() => {
     store = new SqliteStore(new Database(":memory:"));
   });
 
-  it("normalizes path on create", () => {
-    const note = store.createNote("Test", { path: "  Projects//README.md  " });
+  it("normalizes path on create", async () => {
+    const note = await store.createNote("Test", { path: "  Projects//README.md  " });
     expect(note.path).toBe("Projects/README");
   });
 
-  it("normalizes path on update", () => {
-    const note = store.createNote("Test", { path: "Old Path" });
-    const updated = store.updateNote(note.id, { path: "New Path.md" });
+  it("normalizes path on update", async () => {
+    const note = await store.createNote("Test", { path: "Old Path" });
+    const updated = await store.updateNote(note.id, { path: "New Path.md" });
     expect(updated.path).toBe("New Path");
   });
 });
@@ -137,61 +137,61 @@ describe("path normalization in store", () => {
 // Rename cascading
 // ---------------------------------------------------------------------------
 
-describe("rename cascading", () => {
+describe("rename cascading", async () => {
   let store: SqliteStore;
 
   beforeEach(() => {
     store = new SqliteStore(new Database(":memory:"));
   });
 
-  it("updates wikilinks in other notes when path changes", () => {
-    const target = store.createNote("I am the target", { path: "Old Name" });
-    const source = store.createNote("See [[Old Name]] for details.");
+  it("updates wikilinks in other notes when path changes", async () => {
+    const target = await store.createNote("I am the target", { path: "Old Name" });
+    const source = await store.createNote("See [[Old Name]] for details.");
 
     // Verify link exists
-    expect(store.getLinks(source.id, { direction: "outbound" })).toHaveLength(1);
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(1);
 
     // Rename the target
-    store.updateNote(target.id, { path: "New Name" });
+    await store.updateNote(target.id, { path: "New Name" });
 
     // Source content should be updated
-    const updatedSource = store.getNote(source.id)!;
+    const updatedSource = (await store.getNote(source.id))!;
     expect(updatedSource.content).toBe("See [[New Name]] for details.");
 
     // Link should still work
-    const links = store.getLinks(source.id, { direction: "outbound" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
     expect(links).toHaveLength(1);
     expect(links[0].targetId).toBe(target.id);
   });
 
-  it("updates aliased wikilinks", () => {
-    const target = store.createNote("Target", { path: "Old" });
-    const source = store.createNote("See [[Old|click here]] for info.");
+  it("updates aliased wikilinks", async () => {
+    const target = await store.createNote("Target", { path: "Old" });
+    const source = await store.createNote("See [[Old|click here]] for info.");
 
-    store.updateNote(target.id, { path: "New" });
+    await store.updateNote(target.id, { path: "New" });
 
-    const updated = store.getNote(source.id)!;
+    const updated = (await store.getNote(source.id))!;
     expect(updated.content).toBe("See [[New|click here]] for info.");
   });
 
-  it("updates wikilinks with anchors", () => {
-    const target = store.createNote("Target", { path: "Old" });
-    const source = store.createNote("See [[Old#Section]].");
+  it("updates wikilinks with anchors", async () => {
+    const target = await store.createNote("Target", { path: "Old" });
+    const source = await store.createNote("See [[Old#Section]].");
 
-    store.updateNote(target.id, { path: "New" });
+    await store.updateNote(target.id, { path: "New" });
 
-    const updated = store.getNote(source.id)!;
+    const updated = (await store.getNote(source.id))!;
     expect(updated.content).toBe("See [[New#Section]].");
   });
 
-  it("does not update unrelated wikilinks", () => {
-    store.createNote("Target", { path: "Old" });
-    const other = store.createNote("Other", { path: "Other" });
-    const source = store.createNote("See [[Other]] and [[Old]].");
+  it("does not update unrelated wikilinks", async () => {
+    await store.createNote("Target", { path: "Old" });
+    const other = await store.createNote("Other", { path: "Other" });
+    const source = await store.createNote("See [[Other]] and [[Old]].");
 
-    store.updateNote(store.getNoteByPath("Old")!.id, { path: "New" });
+    await store.updateNote((await store.getNoteByPath("Old"))!.id, { path: "New" });
 
-    const updated = store.getNote(source.id)!;
+    const updated = (await store.getNote(source.id))!;
     expect(updated.content).toBe("See [[Other]] and [[New]].");
   });
 });

package/core/src/schema.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 
-export const SCHEMA_VERSION = 8;
+export const SCHEMA_VERSION = 9;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record
@@ -74,6 +74,9 @@ CREATE TABLE IF NOT EXISTS oauth_clients (
 );
 
 -- OAuth: authorization codes (single-use, short-lived)
+-- vault_name pins the code to the vault it was issued for. handleToken
+-- must verify it matches the requested vault — otherwise a code issued
+-- under /vaults/A/oauth/authorize could be redeemed at /vaults/B/oauth/token.
 CREATE TABLE IF NOT EXISTS oauth_codes (
   code TEXT PRIMARY KEY,
   client_id TEXT NOT NULL,
@@ -83,7 +86,8 @@ CREATE TABLE IF NOT EXISTS oauth_codes (
   redirect_uri TEXT NOT NULL,
   expires_at TEXT NOT NULL,
   used INTEGER NOT NULL DEFAULT 0,
-  created_at TEXT NOT NULL
+  created_at TEXT NOT NULL,
+  vault_name TEXT
 );
 
 -- Schema version tracking
@@ -156,6 +160,9 @@ export function initSchema(db: Database): void {
   // this just ensures the tables exist for databases created before v8)
   migrateToV8(db);
 
+  // Migrate v8 → v9: add vault_name column to oauth_codes
+  migrateToV9(db);
+
   // Record schema version
   db.prepare("INSERT OR REPLACE INTO schema_version (version, applied_at) VALUES (?, ?)").run(
     SCHEMA_VERSION,
@@ -254,6 +261,15 @@ function migrateToV8(db: Database): void {
   // CREATE TABLE IF NOT EXISTS. Nothing extra needed here.
 }
 
+function migrateToV9(db: Database): void {
+  // Add vault_name column to existing oauth_codes tables. Codes predating
+  // this migration have NULL vault_name and will fail the token-exchange
+  // vault check — acceptable because codes expire in 10 minutes.
+  if (hasTable(db, "oauth_codes") && !hasColumn(db, "oauth_codes", "vault_name")) {
+    db.exec("ALTER TABLE oauth_codes ADD COLUMN vault_name TEXT");
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;