agentic-drive 0.6.1 → 0.8.0

package/dist/{chunk-EAKQK7ST.js → chunk-R2DUVOJT.js}

@@ -1,9 +1,34 @@
 // src/drive.ts
-import { EraseRefusedError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, SUBJECT_KINDS } from "agentic-identity";
+import { EraseRefusedError, StoreConflictError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, ROLES, SUBJECT_KINDS } from "agentic-identity";
 var ROOT_ID = "root";
 var NODES = "drive_nodes";
 var NAMES = "drive_names";
 var ACTOR_KINDS = PRINCIPAL_KINDS;
+var DECIDED = /* @__PURE__ */ Symbol("decided");
+var ERROR_STATUS = Object.freeze({
+  CROSS_DRIVE: 409,
+  INVALID_SHARE: 400,
+  TOO_MANY_ITEMS: 409,
+  TOO_DEEP: 400,
+  INVALID_EXPIRY: 400,
+  BUSY: 409,
+  BLOB_EXISTS: 500,
+  NOT_FOUND: 404,
+  NAME_TAKEN: 409,
+  INVALID_NAME: 400,
+  INVALID_PATH: 400,
+  INVALID_REF: 400,
+  NOT_A_FOLDER: 400,
+  NOT_A_FILE: 400,
+  MOVE_INTO_SELF: 409,
+  PARENT_GONE: 409,
+  TRASHED: 409,
+  NOT_TRASHED: 409,
+  IS_ROOT: 400,
+  FORBIDDEN: 403,
+  BLOB_MISSING: 500,
+  TOO_LARGE: 413
+});
 var DriveError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -59,6 +84,20 @@ function splitPath(path) {
   if (parts.length > MAX_PATH_SEGMENTS) throw new DriveError("TOO_DEEP", `a path has at most ${MAX_PATH_SEGMENTS} segments`);
   return parts.map(parseName);
 }
+var Ask = class extends Error {
+  constructor(key, ctx, action, node) {
+    super("access answer needed");
+    this.key = key;
+    this.ctx = ctx;
+    this.action = action;
+    this.node = node;
+  }
+  key;
+  ctx;
+  action;
+  node;
+};
+var MAX_ASKS = 100;
 function batch() {
   const writes = [];
   const fresh = /* @__PURE__ */ new Set();
@@ -101,7 +140,24 @@ function createDrive(deps) {
   const onOrphan = deps.onOrphan ?? ((key, error) => console.error(`orphan blob ${key}: ${error instanceof Error ? error.name : "delete failed"}`));
   const sharing = deps.sharing;
   const resourceOf = async (node) => node.id === ROOT_ID ? rootResource(node.owner) : node.id;
-  const can = deps.can ?? (sharing ? async (ctx, action, node) => ctx.principal !== void 0 && (await sharing.can(ctx.principal, ACTION_TO_IDENTITY[action], await resourceOf(node))).allowed : (ctx, _action, node) => node.owner === ctx.owner);
+  const askCan = deps.can ?? (sharing ? async (ctx, action, node) => ctx.principal !== void 0 && (await sharing.can(ctx.principal, ACTION_TO_IDENTITY[action], await resourceOf(node))).allowed : (ctx, _action, node) => node.owner === ctx.owner);
+  const can = async (ctx, action, node) => {
+    const held = ctx[DECIDED];
+    if (!held) return askCan(ctx, action, node);
+    const chain = [];
+    if (sharing) {
+      for (let id = await resourceOf(node), i = 0; id && i <= MAX_ITEM_DEPTH + 1; i++) {
+        const doc = await held.tx.get("resources", id);
+        chain.push(doc?.parentId ?? null);
+        id = typeof doc?.parentId === "string" ? doc.parentId : void 0;
+      }
+    }
+    const key = JSON.stringify([action, node.id, node.owner, node.parentId, node.updatedAt, node.trashed, chain, ctx.owner, ctx.actor, ctx.principal ?? null]);
+    const known = held.answers.get(key);
+    if (known !== void 0) return known;
+    const { [DECIDED]: _held, ...plain } = ctx;
+    throw new Ask(key, plain, action, node);
+  };
   const rootNode = (owner, by) => ({
     id: ROOT_ID,
     owner,
@@ -397,10 +453,30 @@ function createDrive(deps) {
     try {
       return await store.transaction(fn);
     } catch (error) {
-      if (error instanceof Error && /transaction kept conflicting/.test(error.message)) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
+      if (error instanceof StoreConflictError || error instanceof Error && /transaction kept conflicting/.test(error.message)) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
       throw error;
     }
   }
+  async function transactAs(ctx, fn) {
+    const answers = /* @__PURE__ */ new Map();
+    let runs = 0;
+    let asked = false;
+    for (; ; ) {
+      try {
+        return await transact((tx) => {
+          if (++runs > 2 * MAX_ASKS) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
+          if (runs > 1 && !asked) answers.clear();
+          asked = false;
+          return fn(tx, { ...ctx, [DECIDED]: { answers, tx } });
+        });
+      } catch (error) {
+        if (!(error instanceof Ask)) throw error;
+        asked = true;
+        if (answers.size >= MAX_ASKS) throw new DriveError("BUSY", "the drive needed too many access checks. Try again.");
+        answers.set(error.key, await askCan(error.ctx, error.action, error.node));
+      }
+    }
+  }
   function assertInPerson(ctx, what) {
     if (!isInPerson(ctx) || ctx.actor.kind !== "human") throw new DriveError("FORBIDDEN", `only the owner in person can ${what}`);
   }
@@ -550,15 +626,15 @@ function createDrive(deps) {
       return (await children(store, folder.owner, folder.id)).filter((n) => !n.trashed && n.purging !== true).sort((a, b) => a.nameKey < b.nameKey ? -1 : a.nameKey > b.nameKey ? 1 : a.name < b.name ? -1 : 1);
     },
     async mkdir(ctx, path, opts = {}) {
-      return transact(async (tx) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
+        const { parent, name } = await parentAndName(tx, w, ctx2, path, opts.parents ?? false);
         const existing = w.fresh.has(parent.id) ? null : await liveChild(tx, parent, parseName(name).key);
         if (opts.parents && existing?.kind === "folder") {
-          if (!await can(ctx, "read", existing)) throw new DriveError("NOT_FOUND", `no item ${path}`);
+          if (!await can(ctx2, "read", existing)) throw new DriveError("NOT_FOUND", `no item ${path}`);
           return existing;
         }
-        const { node } = await insert(tx, w, ctx, parent, name, { kind: "folder" }, "fail");
+        const { node } = await insert(tx, w, ctx2, parent, name, { kind: "folder" }, "fail");
         await w.apply(tx);
         return node;
       });
@@ -575,10 +651,10 @@ function createDrive(deps) {
       if (!stored) throw new DriveError("BLOB_EXISTS", "a blob with this key already exists");
       let committed;
       try {
-        committed = await transact(async (tx) => {
+        committed = await transactAs(ctx, async (tx, ctx2) => {
           const w = batch();
-          const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
-          const result = await insert(tx, w, ctx, parent, name, { kind: "file", size: data.byteLength, mime, hash, blobKey }, opts.onConflict ?? "fail");
+          const { parent, name } = await parentAndName(tx, w, ctx2, path, opts.parents ?? false);
+          const result = await insert(tx, w, ctx2, parent, name, { kind: "file", size: data.byteLength, mime, hash, blobKey }, opts.onConflict ?? "fail");
           await w.apply(tx);
           return result;
         });
@@ -592,10 +668,10 @@ function createDrive(deps) {
     /** A reference points at a document in another app, such as `docs:<id>`. */
     async putRef(ctx, path, ref, opts = {}) {
       if (!REF.test(ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(ref)}`);
-      return transact(async (tx) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
-        const { node } = await insert(tx, w, ctx, parent, name, { kind: "ref", ref }, opts.onConflict === "replace" ? "fail" : opts.onConflict ?? "fail");
+        const { parent, name } = await parentAndName(tx, w, ctx2, path, opts.parents ?? false);
+        const { node } = await insert(tx, w, ctx2, parent, name, { kind: "ref", ref }, opts.onConflict === "replace" ? "fail" : opts.onConflict ?? "fail");
         await w.apply(tx);
         return node;
       });
@@ -629,35 +705,35 @@ function createDrive(deps) {
     async move(ctx, src, destLoc, opts = {}) {
       const probe = sharing ? await resolve(store, ctx, src) : null;
       const height = probe ? await heightFor(ctx, probe, destLoc) : 0;
-      return transact(async (tx) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const moved = await relocate(tx, w, ctx, await resolve(tx, ctx, src), destLoc, { ...opts, height });
+        const moved = await relocate(tx, w, ctx2, await resolve(tx, ctx2, src), destLoc, { ...opts, height });
         await w.apply(tx);
         return moved;
       });
     },
     async rename(ctx, loc, name) {
-      return transact(async (tx) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const node = await resolve(tx, ctx, loc);
+        const node = await resolve(tx, ctx2, loc);
         if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot change the root");
-        const parent = await rawNode(tx, node.parentId, node.owner, ctx.actor);
+        const parent = await rawNode(tx, node.parentId, node.owner, ctx2.actor);
         if (!parent) throw new DriveError("NOT_FOUND", `the folder of ${node.name} is missing`);
-        const renamed = await relocate(tx, w, ctx, node, parent, { name });
+        const renamed = await relocate(tx, w, ctx2, node, parent, { name });
         await w.apply(tx);
         return renamed;
       });
     },
     /** Hides an item and, for a folder, everything under it. Nothing else changes. */
     async trash(ctx, loc) {
-      return transact(async (tx) => {
-        const node = await resolve(tx, ctx, loc);
+      return transactAs(ctx, async (tx, ctx2) => {
+        const node = await resolve(tx, ctx2, loc);
         if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot trash the root");
-        await need(ctx, "write", node);
+        await need(ctx2, "write", node);
         const claim = await claimId(node.owner, node.parentId, node.nameKey);
         const held = await tx.get(NAMES, claim);
         const t = now();
-        const trashed = { ...node, trashed: true, trashedAt: t, updatedAt: t, ...stamp(ctx, node) };
+        const trashed = { ...node, trashed: true, trashedAt: t, updatedAt: t, ...stamp(ctx2, node) };
         await tx.put(NODES, node.id, trashed);
         if (held?.nodeId === node.id) await tx.delete(NAMES, claim);
         return trashed;
@@ -671,6 +747,15 @@ function createDrive(deps) {
       for (const { data } of page.items) if (data.purging !== true) out.push(data);
       return out.sort((a, b) => (b.trashedAt ?? 0) - (a.trashedAt ?? 0));
     },
+    /** Everything that is in the trash, newest first, each with the path it had before. It reads the whole drive, so a big drive costs more than `listTrash`. */
+    async listTrashWithPaths(ctx) {
+      const all = await ownerNodes(ctx);
+      const byId = new Map(all.map((n) => [n.id, n]));
+      return all.filter((n) => n.trashed).sort((a, b) => (b.trashedAt ?? 0) - (a.trashedAt ?? 0)).flatMap((node) => {
+        const path = pathIn(byId, node, false);
+        return path === null ? [] : [{ node, path }];
+      });
+    },
     /** Puts a trashed item back. It needs a live parent folder. */
     async restore(ctx, id, opts = {}) {
       let height = 0;
@@ -679,20 +764,20 @@ function createDrive(deps) {
         const target = await rawNode(store, opts.parentId, ctx.owner, ctx.actor);
         if (probe?.trashed && target && await can(ctx, "read", target)) height = await heightFor(ctx, probe, target);
       }
-      return transact(async (tx) => {
-        const node = await fetch(tx, ctx, id);
+      return transactAs(ctx, async (tx, ctx2) => {
+        const node = await fetch(tx, ctx2, id);
         if (!node || node.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
         if (!node.trashed) throw new DriveError("NOT_TRASHED", `${node.name} is not in the trash`);
-        await need(ctx, "write", node);
-        const parent = opts.parentId === void 0 ? await rawNode(tx, node.parentId, node.owner, ctx.actor) : await rawNode(tx, opts.parentId, ctx.owner, ctx.actor);
-        const visible = parent !== null && (opts.parentId === void 0 || await can(ctx, "read", parent));
-        if (!parent || !visible || parent.kind !== "folder" || !await isLive(tx, ctx, parent)) {
+        await need(ctx2, "write", node);
+        const parent = opts.parentId === void 0 ? await rawNode(tx, node.parentId, node.owner, ctx2.actor) : await rawNode(tx, opts.parentId, ctx2.owner, ctx2.actor);
+        const visible = parent !== null && (opts.parentId === void 0 || await can(ctx2, "read", parent));
+        if (!parent || !visible || parent.kind !== "folder" || !await isLive(tx, ctx2, parent)) {
           throw new DriveError("PARENT_GONE", `the folder of ${node.name} is gone or in the trash`);
         }
         if (parent.owner !== node.owner) throw new DriveError("CROSS_DRIVE", "an item cannot move into another person's drive");
         if (parent.id !== node.parentId) {
-          await need(ctx, "write", parent);
-          await noClimb(ctx, node, parent);
+          await need(ctx2, "write", parent);
+          await noClimb(ctx2, node, parent);
           await fitsUnder(tx, batch(), parent, height);
         }
         let { name, key } = parseName(node.name);
@@ -701,7 +786,7 @@ function createDrive(deps) {
           name = await freeName(tx, parent.owner, parent.id, name);
           key = parseName(name).key;
         }
-        const restored = { ...node, parentId: parent.id, name, nameKey: key, trashed: false, trashedAt: null, updatedAt: now(), ...stamp(ctx, node) };
+        const restored = { ...node, parentId: parent.id, name, nameKey: key, trashed: false, trashedAt: null, updatedAt: now(), ...stamp(ctx2, node) };
         await tx.put(NODES, restored.id, restored);
         await tx.put(NAMES, await claimId(parent.owner, parent.id, key), { nodeId: restored.id, owner: parent.owner, parentId: parent.id });
         if (sharing && parent.id !== node.parentId) await tx.put("resources", restored.id, await resourceDoc(restored, parent));
@@ -803,6 +888,58 @@ function createDrive(deps) {
       }
       return api.putRef(ctx, dir.endsWith("/") ? `${dir}${input.name}` : `${dir}/${input.name}`, input.ref, { parents: true, onConflict: "rename" });
     },
+    /** The live references to `ref` in the caller's own drive that the caller can read, with their paths, sorted by path. */
+    async findByRef(ctx, ref) {
+      if (!REF.test(ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(ref)}`);
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      const hits = [];
+      const seen = /* @__PURE__ */ new Map();
+      const folder = async (id) => {
+        if (!seen.has(id)) seen.set(id, await rawNode(store, id, ctx.owner, ctx.actor));
+        return seen.get(id) ?? null;
+      };
+      for (const { data } of await allWhere(store, NODES, { owner: ctx.owner, ref })) {
+        const node = data;
+        if (node.kind !== "ref" || node.trashed || node.purging === true) continue;
+        const names = [node.name];
+        let up = node;
+        for (let depth = 0; up && up.parentId !== ROOT_ID && depth < maxDepth; depth++) {
+          up = await folder(up.parentId);
+          if (up === null || up.trashed) break;
+          names.push(up.name);
+        }
+        if (up === null || up.trashed || up.parentId !== ROOT_ID) continue;
+        if (await can(ctx, "read", node)) hits.push({ node, path: `/${names.reverse().join("/")}` });
+      }
+      return hits.sort((a, b) => a.path < b.path ? -1 : 1);
+    },
+    /**
+     * Puts a reference at `path` and gives `claim.subject` the role `claim.role` on it, as one step. If the
+     * grant fails (the caller is not an owner of the item, or the subject is invalid), the reference is
+     * deleted again and the error is thrown, so no half-made item stays. Needs `sharing`. Folders that
+     * `parents` made stay, `onConflict: "replace"` acts as `"fail"` (a rollback could not bring back a replaced item), and an invalid role or subject is refused before anything is written.
+     */
+    async claimRef(ctx, path, ref, claim, opts = {}) {
+      if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+      if (!ctx.principal) throw new DriveError("FORBIDDEN", "sign in to share");
+      const subject = parseSubject(claim.subject);
+      if (!ROLES.includes(claim.role)) throw new DriveError("INVALID_SHARE", `a role is one of ${ROLES.join(", ")}`);
+      const node = await api.putRef(ctx, path, ref, opts);
+      try {
+        await viaSharing(ctx, (s, p) => s.grant(p, node.id, subject, claim.role));
+      } catch (error) {
+        let removed = 0;
+        let gone = false;
+        for (let i = 0; i < 3 && removed === 0 && !gone; i++) {
+          const current = await rawNode(store, node.id, node.owner, ctx.actor, true);
+          if (current === null) gone = true;
+          else removed = await removeNodes([current], void 0, ctx.principal).catch(() => 0);
+        }
+        if (removed === 0 && !gone) console.error(`claimRef could not remove ${node.id} after a failed share. Purge it.`);
+        throw error;
+      }
+      return node;
+    },
     /** An app deleted a document. Its references in this drive go to the trash. Returns how many. */
     async forgetDocument(ctx, ref) {
       if (!REF.test(ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(ref)}`);
@@ -992,167 +1129,6 @@ function createDrive(deps) {
   return Object.fromEntries(Object.entries(api).map(([name, call]) => [name, open.has(name) ? call : guarded(call)]));
 }
 
-// src/adapters/fs.ts
-import { createHash } from "crypto";
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, truncateSync, writeFileSync, writeSync } from "fs";
-import { join } from "path";
-import { assertBlobPutOptions, assertResponseHeaders, createMemoryStore, parseRegion } from "agentic-identity";
-function createFileStore(dir, options = {}) {
-  mkdirSync(dir, { recursive: true });
-  const file = join(dir, "store.jsonl");
-  const inner = createMemoryStore(options);
-  const ready = (async () => {
-    if (!existsSync(file)) return;
-    const text = readFileSync(file, "utf8");
-    const lines = text.split("\n");
-    const tail = lines.pop();
-    const apply = async (changes2) => {
-      for (const [collection, id, doc] of changes2) await (doc ? inner.put(collection, id, doc) : inner.delete(collection, id));
-    };
-    for (const [i, line] of lines.entries()) {
-      if (line === "") continue;
-      try {
-        await apply(JSON.parse(line));
-      } catch {
-        throw new Error(`the journal ${file} has a bad line ${i + 1}`);
-      }
-    }
-    if (tail === "") return;
-    let changes;
-    try {
-      changes = JSON.parse(tail);
-    } catch {
-      truncateSync(file, Buffer.byteLength(text) - Buffer.byteLength(tail));
-      return;
-    }
-    try {
-      await apply(changes);
-    } catch {
-      throw new Error(`the journal ${file} has a bad last line`);
-    }
-    appendFileSync(file, "\n");
-  })();
-  let failed;
-  const keep = (changes) => {
-    if (changes.length === 0) return;
-    try {
-      const fd = openSync(file, "a");
-      try {
-        const line = Buffer.from(`${JSON.stringify(changes)}
-`);
-        for (let done = 0; done < line.length; ) {
-          const wrote = writeSync(fd, line, done);
-          if (wrote <= 0) throw new Error("the journal write stopped short");
-          done += wrote;
-        }
-        fsyncSync(fd);
-      } finally {
-        closeSync(fd);
-      }
-    } catch (error) {
-      failed = error;
-      throw error;
-    }
-  };
-  const open = async () => {
-    await ready;
-    if (failed !== void 0) throw new Error("the journal could not be written, so the store is closed. Open it again.");
-  };
-  const recording = (ops, changes) => ({
-    ...ops,
-    put: async (collection, id, doc) => {
-      await ops.put(collection, id, doc);
-      changes.push([collection, id, doc]);
-    },
-    delete: async (collection, id) => {
-      await ops.delete(collection, id);
-      changes.push([collection, id, null]);
-    }
-  });
-  return {
-    region: inner.region,
-    get: async (c, id) => (await open(), inner.get(c, id)),
-    query: async (c, q) => (await open(), inner.query(c, q)),
-    async put(collection, id, doc) {
-      await open();
-      await inner.put(collection, id, doc);
-      keep([[collection, id, doc]]);
-    },
-    async delete(collection, id) {
-      await open();
-      await inner.delete(collection, id);
-      keep([[collection, id, null]]);
-    },
-    async transaction(fn) {
-      await open();
-      let changes = [];
-      const result = await inner.transaction((tx) => {
-        changes = [];
-        return fn(recording(tx, changes));
-      });
-      keep(changes);
-      return result;
-    }
-  };
-}
-var versionOf = (data) => createHash("sha256").update(data).digest("hex");
-function createFileBlobs(dir, options = {}) {
-  mkdirSync(dir, { recursive: true });
-  const path = (key) => join(dir, createHash("sha256").update(key).digest("hex"));
-  const need = (key) => {
-    if (key === "") throw new Error("blob key must not be empty");
-  };
-  const now = options.now ?? Date.now;
-  return {
-    region: options.region === void 0 ? "unknown" : parseRegion(options.region),
-    async put(key, data, opts) {
-      need(key);
-      assertBlobPutOptions(opts);
-      const current = existsSync(path(key)) ? versionOf(readFileSync(path(key))) : void 0;
-      if (opts?.ifNoneMatch === "*" && current !== void 0 || opts?.ifMatch !== void 0 && current !== opts.ifMatch) return null;
-      const tmp = `${path(key)}.tmp`;
-      writeFileSync(tmp, data);
-      if (opts?.contentType) writeFileSync(`${path(key)}.type`, opts.contentType);
-      else rmSync(`${path(key)}.type`, { force: true });
-      renameSync(tmp, path(key));
-      return { version: versionOf(data) };
-    },
-    async get(key) {
-      need(key);
-      if (!existsSync(path(key))) return null;
-      const type = existsSync(`${path(key)}.type`) ? readFileSync(`${path(key)}.type`, "utf8") : void 0;
-      const data = new Uint8Array(readFileSync(path(key)));
-      return { data, version: versionOf(data), ...type ? { contentType: type } : {} };
-    },
-    async head(key) {
-      need(key);
-      if (!existsSync(path(key))) return null;
-      const type = existsSync(`${path(key)}.type`) ? readFileSync(`${path(key)}.type`, "utf8") : void 0;
-      const data = readFileSync(path(key));
-      return { size: data.length, version: versionOf(data), ...type ? { contentType: type } : {} };
-    },
-    async delete(key) {
-      need(key);
-      rmSync(path(key), { force: true });
-      rmSync(`${path(key)}.type`, { force: true });
-    },
-    /** A local path with its expiry. Nothing serves or checks it: it exists so the port is whole. */
-    async signedUrl(key, opts) {
-      need(key);
-      const { method, expiresInSeconds } = opts;
-      assertResponseHeaders(opts);
-      if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 604800) {
-        throw new RangeError("expiresInSeconds must be an integer from 1 to 604800");
-      }
-      const extra = [
-        opts.responseContentDisposition === void 0 ? "" : `&disposition=${encodeURIComponent(opts.responseContentDisposition)}`,
-        opts.responseContentType === void 0 ? "" : `&type=${encodeURIComponent(opts.responseContentType)}`
-      ].join("");
-      return `file://${path(key)}?method=${method}&expires=${now() + expiresInSeconds * 1e3}${extra}`;
-    }
-  };
-}
-
 // src/upload.ts
 var DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
 var SIGNATURES = [
@@ -1353,14 +1329,93 @@ async function authenticate(request, store, now) {
   if (principal instanceof Response) return null;
   return { owner: principal.chain[0].id, actor: { id: principal.principalId, kind: principal.kind }, principal };
 }
+async function inviteIdentity(store, actorId) {
+  const user = await store.get("users", actorId);
+  const agent = await store.get("principals", actorId);
+  return {
+    ...user?.emailVerified === true && typeof user.email === "string" ? { email: user.email } : {},
+    ...typeof agent?.handle === "string" ? { handle: agent.handle } : {}
+  };
+}
+
+// src/migrate.ts
+var PAGE = 10;
+var isText = (v) => typeof v === "string" && v !== "";
+async function walk(store, options, fix) {
+  const { maxPages } = options;
+  if (maxPages !== void 0 && !(Number.isSafeInteger(maxPages) && maxPages > 0)) {
+    throw new Error("maxPages must be a positive whole number");
+  }
+  let fixed = 0;
+  let cursor = options.cursor;
+  for (let pages = 0; maxPages === void 0 || pages < maxPages; pages++) {
+    const page = await store.query("drive_nodes", { limit: PAGE, cursor });
+    fixed += await store.transaction(async (tx) => {
+      const items = [];
+      for (const item of page.items) {
+        const data = await tx.get("drive_nodes", item.id);
+        if (data) items.push({ id: item.id, data });
+      }
+      return fix(tx, items);
+    });
+    cursor = page.nextCursor;
+    if (!cursor) return { fixed };
+  }
+  return { fixed, nextCursor: cursor };
+}
+function backfillAuthorIds(store, options = {}) {
+  return walk(store, options, async (tx, items) => {
+    let count = 0;
+    for (const { id, data } of items) {
+      const created = data.createdBy?.id;
+      const updated = data.updatedBy?.id;
+      if (!isText(created) || !isText(updated)) {
+        throw new Error(`item ${id} has no author. Fix it before you run the backfill again.`);
+      }
+      if (data.createdById === created && data.updatedById === updated) continue;
+      await tx.put("drive_nodes", id, { ...data, createdById: created, updatedById: updated });
+      count++;
+    }
+    return count;
+  });
+}
+function backfillResources(store, options = {}) {
+  return walk(store, options, async (tx, items) => {
+    const missing = [];
+    for (const { id, data } of items) {
+      if (!isText(data.owner) || !isText(data.parentId)) {
+        throw new Error(`item ${id} has no owner or parent. Fix it before you run the backfill again.`);
+      }
+      if (await tx.get("resources", id)) continue;
+      missing.push({ id, parentId: data.parentId === ROOT_ID ? await rootResource(data.owner) : data.parentId });
+    }
+    for (const { id, parentId } of missing) await tx.put("resources", id, { id, type: "drive", parentId });
+    return missing.length;
+  });
+}
 
 // src/local.ts
-import { createHash as createHash2 } from "crypto";
-import { join as join2 } from "path";
-import { isMachineMade, isScope, issueCredential, revokeCredential } from "agentic-identity";
-function openLocal(dir) {
-  const store = createFileStore(join2(dir, "db"));
-  return { store, drive: createDrive({ store, blobs: createFileBlobs(join2(dir, "blobs")) }) };
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { join } from "path";
+import { createSharing, isMachineMade, isScope, issueCredential, revokeCredential } from "agentic-identity";
+import { createFileBlobs, createFileStore } from "agentic-identity/file";
+function openLocal(dir, opts = {}) {
+  if (!opts.beforeImport && existsSync(join(dir, "db", "store.jsonl")) && !existsSync(join(dir, "store.json"))) {
+    throw new Error(`${dir} holds data from an older version. Run importLegacyLocal(dir, store, blobs) first: open it with openLocal(dir, { beforeImport: true }).`);
+  }
+  const store = createFileStore({ path: join(dir, "store.json") });
+  const blobs = createFileBlobs({ dir: join(dir, "blobs") });
+  return { store, blobs, drive: createDrive({ store, blobs, sharing: createSharing(store) }) };
+}
+async function ensureSharing(store) {
+  if (await store.get("drive_meta", "sharing")) return;
+  try {
+    await backfillResources(store);
+  } catch (error) {
+    throw new Error(`the one-time sharing backfill of local items failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  await store.put("drive_meta", "sharing", { backfilledAt: Date.now() });
 }
 var AuthError = class extends Error {
   code = "UNAUTHENTICATED";
@@ -1402,7 +1457,7 @@ async function issueKey(store, principalId, label) {
   return issueCredential(store, { principalId, kind: "api_key", ...label ? { label } : {} });
 }
 async function revokeKey(store, token) {
-  if (!await store.get("credentials", createHash2("sha256").update(token).digest("hex"))) throw new DriveError("NOT_FOUND", "no such key");
+  if (!await store.get("credentials", createHash("sha256").update(token).digest("hex"))) throw new DriveError("NOT_FOUND", "no such key");
   await revokeCredential(store, token, Date.now());
 }
 function publicNode(node, path) {
@@ -1414,16 +1469,14 @@ function publicNode(node, path) {
 export {
   ROOT_ID,
   ACTOR_KINDS,
+  ERROR_STATUS,
   DriveError,
   DEFAULT_URL_SECONDS,
   safeMime,
   parseName,
-  rootResource,
   subjectKindOf,
   parseSubject,
   createDrive,
-  createFileStore,
-  createFileBlobs,
   DEFAULT_MAX_BYTES,
   sniffMime,
   upload,
@@ -1431,7 +1484,11 @@ export {
   readZip,
   buildExport,
   authenticate,
+  inviteIdentity,
+  backfillAuthorIds,
+  backfillResources,
   openLocal,
+  ensureSharing,
   AuthError,
   NO_TOKEN,
   resolveToken,