agentic-drive 0.1.0 → 0.2.0

package/dist/{chunk-QRGKXPLX.js → chunk-6CWBHSJ7.js}

@@ -1,4 +1,5 @@
 // src/drive.ts
+import { MAX_FOLDER_DEPTH } from "agentic-identity";
 var ROOT_ID = "root";
 var NODES = "drive_nodes";
 var NAMES = "drive_names";
@@ -14,6 +15,8 @@ var DriveError = class extends Error {
 var MAX_PATH_SEGMENTS = 64;
 var DEFAULT_MAX_DEPTH = 256;
 var CHUNK = 25;
+var SHARED_CHUNK = 10;
+var HEIGHT_BUDGET = 200;
 var DEFAULT_URL_SECONDS = 900;
 var MAX_URL_SECONDS = 3600;
 var OPAQUE = "application/octet-stream";
@@ -59,8 +62,10 @@ function splitPath(path) {
 function batch() {
   const writes = [];
   const fresh = /* @__PURE__ */ new Set();
+  const depths = /* @__PURE__ */ new Map();
   return {
     fresh,
+    depths,
     put: (collection, id, doc) => void writes.push({ collection, id, doc }),
     remove: (collection, id) => void writes.push({ collection, id, doc: null }),
     async apply(ops) {
@@ -69,16 +74,25 @@ function batch() {
   };
 }
 var claimId = (owner, parentId, key) => sha256Hex(new TextEncoder().encode(`${owner}\0${parentId}\0${key}`));
+var rootResource = async (owner) => `drive-root-${(await sha256Hex(new TextEncoder().encode(owner))).slice(0, 32)}`;
+var ACTION_TO_IDENTITY = { read: "read", write: "write", delete: "admin" };
+var MAX_ITEM_DEPTH = MAX_FOLDER_DEPTH - 1;
+var VISITOR = { id: "", kind: "human" };
+var appOf = (node) => node.kind === "ref" && node.ref ? node.ref.split(":")[0] : null;
+var ERASED = "erased";
+var SHARE_ERROR = /^(invalid|give an|expiresAt|expiresInMs|resource exists|the last owner)/;
 function createDrive(deps) {
   const { store, blobs } = deps;
   const now = deps.now ?? Date.now;
   const newId = deps.newId ?? (() => globalThis.crypto.randomUUID());
   const maxDepth = deps.maxDepth ?? DEFAULT_MAX_DEPTH;
   const onOrphan = deps.onOrphan ?? ((key, error) => console.error(`orphan blob ${key}: ${error instanceof Error ? error.name : "delete failed"}`));
-  const can = deps.can ?? ((ctx, _action, node) => node.owner === ctx.owner);
-  const rootNode = (ctx) => ({
+  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 rootNode = (owner, by) => ({
     id: ROOT_ID,
-    owner: ctx.owner,
+    owner,
     parentId: "",
     kind: "folder",
     name: "",
@@ -90,16 +104,24 @@ function createDrive(deps) {
     blobKey: null,
     createdAt: 0,
     updatedAt: 0,
-    createdBy: ctx.actor,
-    updatedBy: ctx.actor,
+    createdBy: by,
+    updatedBy: by,
+    createdById: by.id,
+    updatedById: by.id,
     trashed: false,
     trashedAt: null,
     purging: false
   });
   const who = (ctx) => ({ id: ctx.actor.id, kind: ctx.actor.kind });
+  const stamp = (ctx, node) => ({ createdById: node.createdById ?? node.createdBy.id, updatedBy: who(ctx), updatedById: ctx.actor.id });
+  const resourceDoc = async (node, parent) => ({ id: node.id, type: "drive", parentId: await resourceOf(parent) });
+  async function rawNode(ops, id, owner, by, withMarked = false) {
+    const node = id === ROOT_ID ? rootNode(owner, by) : await ops.get(NODES, id);
+    return node && (withMarked || node.purging !== true) ? node : null;
+  }
   async function fetch(ops, ctx, id, purgeAgain = false) {
-    const node = id === ROOT_ID ? rootNode(ctx) : await ops.get(NODES, id);
-    return node && (purgeAgain || node.purging !== true) && await can(ctx, "read", node) ? node : null;
+    const node = await rawNode(ops, id, ctx.owner, ctx.actor, purgeAgain);
+    return node && await can(ctx, "read", node) ? node : null;
   }
   async function need(ctx, action, node) {
     if (!await can(ctx, action, node)) throw new DriveError("FORBIDDEN", `not allowed to ${action} ${node.id}`);
@@ -119,45 +141,106 @@ function createDrive(deps) {
     const node = found && !found.trashed && found.purging !== true && found.parentId === parentId && found.nameKey === key ? found : null;
     return { taken: claim !== null, node };
   }
-  const liveChild = async (ops, ctx, parentId, key) => (await claimed(ops, ctx.owner, parentId, key)).node;
+  const liveChild = async (ops, folder, key) => (await claimed(ops, folder.owner, folder.id, key)).node;
   async function isLive(ops, ctx, node) {
     for (let n = node, depth = 0; n && depth < maxDepth; depth++) {
       if (n.trashed) return false;
       if (n.id === ROOT_ID) return true;
-      n = await fetch(ops, ctx, n.parentId);
+      n = await rawNode(ops, n.parentId, n.owner, ctx.actor);
     }
     return false;
   }
+  async function depthOf(ops, w, node) {
+    let depth = 0;
+    for (let n = node; n && n.id !== ROOT_ID; ) {
+      const known = w.depths.get(n.id);
+      if (known !== void 0) return depth + known;
+      if (++depth > MAX_ITEM_DEPTH) return depth;
+      n = await rawNode(ops, n.parentId, n.owner, node.createdBy);
+      if (n === null) return MAX_ITEM_DEPTH + 1;
+    }
+    return depth;
+  }
+  async function heightOf(ops, folder) {
+    let level = [folder];
+    let queries = 0;
+    for (let height = 1; height <= MAX_ITEM_DEPTH; height++) {
+      const next = [];
+      for (const f of level) {
+        for (let cursor; ; ) {
+          if (++queries > HEIGHT_BUDGET) throw new DriveError("TOO_MANY_ITEMS", `${folder.name} has too many folders to count. Move its parts one by one.`);
+          const page = await ops.query(NODES, { where: { owner: f.owner, parentId: f.id, kind: "folder" }, limit: 100, cursor });
+          next.push(...page.items.map((item) => item.data));
+          if (!page.nextCursor) break;
+          cursor = page.nextCursor;
+        }
+      }
+      if (next.length === 0) return height;
+      level = next;
+    }
+    return MAX_ITEM_DEPTH + 1;
+  }
+  async function heightFor(ctx, node, dest) {
+    if (!sharing || node.kind !== "folder") return 0;
+    const target = typeof dest === "string" ? await resolve(store, ctx, dest) : dest;
+    if (target.id === node.parentId) return 0;
+    const w = batch();
+    if (await depthOf(store, w, target) + 1 <= await depthOf(store, w, node)) return 0;
+    return heightOf(store, node);
+  }
+  async function noClimb(ctx, node, dest) {
+    const person = ctx.principal ? { ...ctx, principal: { ...ctx.principal, scopes: ["drive:admin"] } } : ctx;
+    if (await can(person, "delete", dest) && !await can(person, "delete", node)) {
+      throw new DriveError("FORBIDDEN", "moving into a folder you own needs owner on the item");
+    }
+  }
+  async function fitsUnder(ops, w, dest, height) {
+    if (sharing && await depthOf(ops, w, dest) + 1 + height > MAX_ITEM_DEPTH) {
+      throw new DriveError("TOO_DEEP", `an item can sit at most ${MAX_ITEM_DEPTH} folders deep`);
+    }
+  }
+  async function startOf(ops, ctx, loc) {
+    if (loc.startsWith("/")) {
+      const start = rootNode(ctx.owner, ctx.actor);
+      if (!await can(ctx, "read", start)) throw new DriveError("NOT_FOUND", `no item ${loc}`);
+      return { start, segs: splitPath(loc) };
+    }
+    const slash = loc.indexOf("/");
+    const base = await resolve(ops, ctx, loc.slice(0, slash));
+    if (base.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${base.name} is not a folder`);
+    return { start: base, segs: splitPath(`/${loc.slice(slash + 1)}`) };
+  }
   async function resolve(ops, ctx, loc) {
-    if (!loc.startsWith("/")) {
+    if (!loc.includes("/")) {
       const node2 = await fetch(ops, ctx, loc);
       if (!node2) throw new DriveError("NOT_FOUND", `no item ${loc}`);
       if (!await isLive(ops, ctx, node2)) throw new DriveError("TRASHED", `${loc} is in the trash`);
       return node2;
     }
-    let node = rootNode(ctx);
-    for (const seg of splitPath(loc)) {
+    const { start, segs } = await startOf(ops, ctx, loc);
+    let node = start;
+    for (const seg of segs) {
       if (node.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${node.name} is not a folder`);
-      const next = await liveChild(ops, ctx, node.id, seg.key);
+      const next = await liveChild(ops, node, seg.key);
       if (!next) throw new DriveError("NOT_FOUND", `no item ${loc}`);
       node = next;
     }
     if (!await can(ctx, "read", node)) throw new DriveError("NOT_FOUND", `no item ${loc}`);
     return node;
   }
-  async function freeName(ops, ctx, parentId, name) {
+  async function freeName(ops, owner, parentId, name) {
     const dot = name.lastIndexOf(".");
     const [base, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
     for (let n = 2; ; n++) {
       const candidate = `${base} (${n})${ext}`;
-      if (!(await claimed(ops, ctx.owner, parentId, parseName(candidate).key)).taken) return candidate;
+      if (!(await claimed(ops, owner, parentId, parseName(candidate).key)).taken) return candidate;
     }
   }
-  async function folderAt(ops, w, ctx, segs, create) {
-    let node = rootNode(ctx);
+  async function folderAt(ops, w, ctx, start, segs, create) {
+    let node = start;
     for (const seg of segs) {
       if (node.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${node.name} is not a folder`);
-      let next = w.fresh.has(node.id) ? null : await liveChild(ops, ctx, node.id, seg.key);
+      let next = w.fresh.has(node.id) ? null : await liveChild(ops, node, seg.key);
       if (!next) {
         if (!create) throw new DriveError("NOT_FOUND", `no folder ${seg.name}`);
         next = (await insert(ops, w, ctx, node, seg.name, { kind: "folder" }, "fail")).node;
@@ -172,21 +255,27 @@ function createDrive(deps) {
     let { name, key } = parseName(rawName);
     const empty = w.fresh.has(parent.id);
     if (!empty) await need(ctx, "write", parent);
-    const slot = empty ? null : await claimed(ops, ctx.owner, parent.id, key);
+    const slot = empty ? null : await claimed(ops, parent.owner, parent.id, key);
     if (slot?.taken) {
       if (onConflict === "replace" && slot.node?.kind === "file" && fields.kind === "file") {
-        const node2 = { ...slot.node, ...fields, updatedAt: now(), updatedBy: who(ctx) };
+        const node2 = { ...slot.node, ...fields, updatedAt: now(), ...stamp(ctx, slot.node) };
         w.put(NODES, node2.id, node2);
         return { node: node2, replacedBlob: slot.node.blobKey };
       }
       if (onConflict !== "rename") throw new DriveError("NAME_TAKEN", `"${name}" already exists`);
-      name = await freeName(ops, ctx, parent.id, name);
+      name = await freeName(ops, parent.owner, parent.id, name);
       key = parseName(name).key;
     }
+    const id = newId();
+    if (sharing) {
+      const depth = await depthOf(ops, w, parent) + 1;
+      if (depth > MAX_ITEM_DEPTH) throw new DriveError("TOO_DEEP", `an item can sit at most ${MAX_ITEM_DEPTH} folders deep`);
+      w.depths.set(id, depth);
+    }
     const t = now();
     const node = {
-      id: newId(),
-      owner: ctx.owner,
+      id,
+      owner: parent.owner,
       parentId: parent.id,
       kind: "file",
       name,
@@ -200,53 +289,62 @@ function createDrive(deps) {
       updatedAt: t,
       createdBy: who(ctx),
       updatedBy: who(ctx),
+      createdById: ctx.actor.id,
+      updatedById: ctx.actor.id,
       trashed: false,
       trashedAt: null,
       purging: false,
       ...fields
     };
     w.put(NODES, node.id, node);
-    w.put(NAMES, await claimId(ctx.owner, parent.id, key), { nodeId: node.id, owner: ctx.owner, parentId: parent.id });
+    w.put(NAMES, await claimId(parent.owner, parent.id, key), { nodeId: node.id, owner: parent.owner, parentId: parent.id });
+    if (sharing) w.put("resources", node.id, await resourceDoc(node, parent));
     return { node, replacedBlob: null };
   }
   async function parentAndName(ops, w, ctx, path, parents) {
-    const segs = splitPath(path);
+    const { start, segs } = await startOf(ops, ctx, path);
     const last = segs.pop();
-    if (!last) throw new DriveError("IS_ROOT", "the root already exists");
-    return { parent: await folderAt(ops, w, ctx, segs, parents), name: last.name };
+    if (!last) throw start.id === ROOT_ID ? new DriveError("IS_ROOT", "the root already exists") : new DriveError("INVALID_PATH", "name an item inside the folder");
+    return { parent: await folderAt(ops, w, ctx, start, segs, parents), name: last.name };
   }
   async function relocate(ops, w, ctx, node, destLoc, opts) {
     if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot change the root");
-    const dest = await resolve(ops, ctx, destLoc);
+    const dest = typeof destLoc === "string" ? await resolve(ops, ctx, destLoc) : destLoc;
     if (dest.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${dest.name} is not a folder`);
+    if (dest.owner !== node.owner) throw new DriveError("CROSS_DRIVE", "an item cannot move into another person's drive");
     for (let n = dest, depth = 0; n.id !== ROOT_ID; depth++) {
       if (n.id === node.id) throw new DriveError("MOVE_INTO_SELF", `cannot move ${node.name} into itself`);
       if (depth >= maxDepth) throw new DriveError("TOO_DEEP", `the destination is deeper than ${maxDepth} folders`);
-      const parent = await fetch(ops, ctx, n.parentId);
+      const parent = await rawNode(ops, n.parentId, n.owner, ctx.actor);
       if (!parent) throw new DriveError("NOT_FOUND", `a parent folder of ${dest.name} is missing`);
       n = parent;
     }
     await need(ctx, "write", node);
-    await need(ctx, "write", dest);
+    if (dest.id !== node.parentId) {
+      await need(ctx, "write", dest);
+      await noClimb(ctx, node, dest);
+      await fitsUnder(ops, w, dest, opts.height ?? 0);
+    }
     let { name, key } = parseName(opts.name ?? node.name);
-    const slot = await claimed(ops, ctx.owner, dest.id, key);
+    const slot = await claimed(ops, dest.owner, dest.id, key);
     if (slot.taken && slot.node?.id !== node.id) {
       if (opts.onConflict !== "rename") throw new DriveError("NAME_TAKEN", `"${name}" already exists`);
-      name = await freeName(ops, ctx, dest.id, name);
+      name = await freeName(ops, dest.owner, dest.id, name);
       key = parseName(name).key;
     }
-    const moved = { ...node, parentId: dest.id, name, nameKey: key, updatedAt: now(), updatedBy: who(ctx) };
+    const moved = { ...node, parentId: dest.id, name, nameKey: key, updatedAt: now(), ...stamp(ctx, node) };
     w.put(NODES, moved.id, moved);
-    const [from, to] = [await claimId(ctx.owner, node.parentId, node.nameKey), await claimId(ctx.owner, dest.id, key)];
+    const [from, to] = [await claimId(node.owner, node.parentId, node.nameKey), await claimId(dest.owner, dest.id, key)];
     if (from !== to) {
       if ((await ops.get(NAMES, from))?.nodeId === node.id) w.remove(NAMES, from);
-      w.put(NAMES, to, { nodeId: moved.id, owner: ctx.owner, parentId: dest.id });
+      w.put(NAMES, to, { nodeId: moved.id, owner: dest.owner, parentId: dest.id });
     }
+    if (sharing && dest.id !== node.parentId) w.put("resources", moved.id, await resourceDoc(moved, dest));
     return moved;
   }
-  async function isUnreferenced(ctx, blobKey) {
+  async function isUnreferenced(blobKey) {
     try {
-      return (await store.query(NODES, { where: { owner: ctx.owner, blobKey }, limit: 1 })).items.length === 0;
+      return (await store.query(NODES, { where: { blobKey }, limit: 1 })).items.length === 0;
     } catch (error) {
       onOrphan(blobKey, error);
       return false;
@@ -259,17 +357,19 @@ function createDrive(deps) {
       onOrphan(key, error);
     }
   }
-  async function ownerNodes(ctx, withMarked = false) {
-    const root = rootNode(ctx);
-    if (!await can(ctx, "read", root)) throw new DriveError("FORBIDDEN", "not allowed to read this drive");
+  async function rawOwnerNodes(owner, withMarked) {
     const out = [];
     for (let cursor; ; ) {
-      const page = await store.query(NODES, { where: { owner: ctx.owner }, limit: 100, cursor });
+      const page = await store.query(NODES, { where: { owner }, limit: 100, cursor });
       out.push(...page.items.map((item) => item.data).filter((node) => withMarked || node.purging !== true));
       if (!page.nextCursor) return out;
       cursor = page.nextCursor;
     }
   }
+  async function ownerNodes(ctx, withMarked = false) {
+    if (!await can(ctx, "read", rootNode(ctx.owner, ctx.actor))) throw new DriveError("FORBIDDEN", "not allowed to read this drive");
+    return rawOwnerNodes(ctx.owner, withMarked);
+  }
   function pathIn(byId, node, liveOnly) {
     const names = [];
     for (let n = node, depth = 0; depth < 1e3; depth++) {
@@ -289,12 +389,72 @@ function createDrive(deps) {
       throw error;
     }
   }
+  function assertInPerson(ctx, what) {
+    if (!isInPerson(ctx) || ctx.actor.kind !== "human") throw new DriveError("FORBIDDEN", `only the owner in person can ${what}`);
+  }
+  const subjectOf = (ctx) => ({ id: ctx.owner, kind: ctx.principal?.chain[0]?.kind ?? (isInPerson(ctx) ? ctx.actor.kind : null) });
+  async function allWhere(ops, collection, where, orderBy) {
+    const out = [];
+    for (let cursor; ; ) {
+      const page = await ops.query(collection, { where, ...orderBy ? { orderBy } : {}, limit: 100, cursor });
+      out.push(...page.items);
+      if (!page.nextCursor) return out;
+      cursor = page.nextCursor;
+    }
+  }
+  const isInPerson = (ctx) => ctx.principal === void 0 ? ctx.actor.kind === "human" && ctx.actor.id === ctx.owner : ctx.principal.kind === "human" && ctx.principal.chain.length === 1 && ctx.actor.id === ctx.owner;
+  const MAX_ACTORS = 1e3;
+  async function actorsOf(ops, id) {
+    const ownedAgents = (await allWhere(ops, "principals", { ownerId: id })).map((p) => p.id);
+    const actors = [id, ...ownedAgents];
+    for (let depth = 0, from = 0; from < actors.length && depth < 8; depth++) {
+      const next = actors.length;
+      for (; from < next; from++) for (const child of await allWhere(ops, "principals", { parentId: actors[from] })) if (!actors.includes(child.id)) actors.push(child.id);
+      if (actors.length > MAX_ACTORS) throw new DriveError("TOO_MANY_ITEMS", `a person can have at most ${MAX_ACTORS} agents here`);
+    }
+    return { actors, ownedAgents };
+  }
+  async function madeBy(ops, actors) {
+    const made = /* @__PURE__ */ new Map();
+    for (const actor of actors) for (const field of ["createdById", "updatedById"]) for (const { data } of await allWhere(ops, NODES, { [field]: actor })) made.set(data.id, data);
+    return [...made.values()];
+  }
+  async function eraseDrive(owner) {
+    let removed = 0;
+    for (let pass = 0; pass < 5; pass++) {
+      const all = await rawOwnerNodes(owner, true);
+      if (all.length === 0) {
+        const rootId = await rootResource(owner);
+        await transact(async (tx) => {
+          const shares = sharing ? await sharesOf(tx, rootId) : [];
+          for (const share of shares) await tx.delete(share.collection, share.id);
+          if (sharing) await tx.delete("resources", rootId);
+        });
+        return removed;
+      }
+      removed += await removeNodes(all);
+    }
+    throw new DriveError("BUSY", "the drive kept changing while it was deleted. Run it again.");
+  }
+  async function sharesOf(ops, resourceId) {
+    const out = [];
+    for (const collection of ["grants", "links", "invites"]) {
+      for (let cursor; ; ) {
+        const page = await ops.query(collection, { where: { resourceId }, limit: 100, cursor });
+        out.push(...page.items.map((item) => ({ collection, id: item.id })));
+        if (!page.nextCursor) break;
+        cursor = page.nextCursor;
+      }
+    }
+    return out;
+  }
   async function removeNodes(nodes, top) {
     const unchanged = (now2, seen) => now2 !== null && now2.trashed === seen.trashed && now2.parentId === seen.parentId && now2.updatedAt === seen.updatedAt;
+    const size = sharing ? SHARED_CHUNK : CHUNK;
     const marked = [];
     const markedIds = /* @__PURE__ */ new Set();
-    for (let i = 0; i < nodes.length; i += CHUNK) {
-      const slice = nodes.slice(i, i + CHUNK);
+    for (let i = 0; i < nodes.length; i += size) {
+      const slice = nodes.slice(i, i + size);
       for (const node of slice) {
         if (node.purging === true) {
           marked.push(node);
@@ -323,23 +483,35 @@ function createDrive(deps) {
       if (top && i === 0 && !markedIds.has(top.id)) throw new DriveError("BUSY", `${top.name} changed during the purge. Nothing was deleted.`);
     }
     const rows = marked.reverse();
-    for (let i = 0; i < rows.length; i += CHUNK) {
-      const chunk = rows.slice(i, i + CHUNK);
+    for (let i = 0; i < rows.length; i += size) {
+      const chunk = rows.slice(i, i + size);
       for (const node of chunk) if (node.blobKey) await blobs.delete(node.blobKey);
       await transact(async (tx) => {
         const held = [];
         for (const node of chunk) {
           const claim = node.trashed ? null : await claimId(node.owner, node.parentId, node.nameKey);
-          held.push({ node, claim, owns: claim !== null && (await tx.get(NAMES, claim))?.nodeId === node.id });
+          const shares = sharing ? await sharesOf(tx, node.id) : [];
+          held.push({ node, claim, owns: claim !== null && (await tx.get(NAMES, claim))?.nodeId === node.id, shares });
         }
-        for (const { node, claim, owns } of held) {
+        for (const { node, claim, owns, shares } of held) {
           await tx.delete(NODES, node.id);
           if (claim && owns) await tx.delete(NAMES, claim);
+          if (sharing) await tx.delete("resources", node.id);
+          for (const share of shares) await tx.delete(share.collection, share.id);
         }
       });
     }
     return marked.length;
   }
+  async function openShared(principal, id, linkToken) {
+    if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+    const node = await rawNode(store, id, "", VISITOR);
+    if (!node || node.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
+    const decision = await sharing.can(principal, "read", id, linkToken === void 0 ? {} : { linkToken });
+    if (!decision.allowed) throw new DriveError("NOT_FOUND", `no item ${id}`);
+    if (!await isLive(store, { owner: node.owner, actor: node.createdBy }, node)) throw new DriveError("TRASHED", `${id} is in the trash`);
+    return node;
+  }
   const api = {
     async stat(ctx, loc) {
       return resolve(store, ctx, loc);
@@ -354,8 +526,11 @@ function createDrive(deps) {
       return transact(async (tx) => {
         const w = batch();
         const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
-        const existing = w.fresh.has(parent.id) ? null : await liveChild(tx, ctx, parent.id, parseName(name).key);
-        if (opts.parents && existing?.kind === "folder") return existing;
+        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}`);
+          return existing;
+        }
         const { node } = await insert(tx, w, ctx, parent, name, { kind: "folder" }, "fail");
         await w.apply(tx);
         return node;
@@ -368,7 +543,7 @@ function createDrive(deps) {
     async putFile(ctx, path, data, opts = {}) {
       const mime = opts.mime === void 0 ? null : safeMime(opts.mime);
       const hash = await sha256Hex(data);
-      const blobKey = `${ctx.owner}/${newId()}`;
+      const blobKey = `blobs/${newId()}`;
       const stored = await blobs.put(blobKey, data, { ifNoneMatch: "*", ...mime ? { contentType: mime } : {} });
       if (!stored) throw new DriveError("BLOB_EXISTS", "a blob with this key already exists");
       let committed;
@@ -381,7 +556,7 @@ function createDrive(deps) {
           return result;
         });
       } catch (error) {
-        if (await isUnreferenced(ctx, blobKey)) await dropBlob(blobKey);
+        if (await isUnreferenced(blobKey)) await dropBlob(blobKey);
         throw error;
       }
       if (committed.replacedBlob) await dropBlob(committed.replacedBlob);
@@ -425,9 +600,11 @@ 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) => {
         const w = batch();
-        const moved = await relocate(tx, w, ctx, await resolve(tx, ctx, src), destLoc, opts);
+        const moved = await relocate(tx, w, ctx, await resolve(tx, ctx, src), destLoc, { ...opts, height });
         await w.apply(tx);
         return moved;
       });
@@ -436,7 +613,10 @@ function createDrive(deps) {
       return transact(async (tx) => {
         const w = batch();
         const node = await resolve(tx, ctx, loc);
-        const renamed = await relocate(tx, w, ctx, node, node.parentId, { name });
+        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);
+        if (!parent) throw new DriveError("NOT_FOUND", `the folder of ${node.name} is missing`);
+        const renamed = await relocate(tx, w, ctx, node, parent, { name });
         await w.apply(tx);
         return renamed;
       });
@@ -446,11 +626,11 @@ function createDrive(deps) {
       return transact(async (tx) => {
         const node = await resolve(tx, ctx, loc);
         if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot trash the root");
-        await need(ctx, "delete", node);
+        await need(ctx, "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, updatedBy: who(ctx) };
+        const trashed = { ...node, trashed: true, trashedAt: t, updatedAt: t, ...stamp(ctx, node) };
         await tx.put(NODES, node.id, trashed);
         if (held?.nodeId === node.id) await tx.delete(NAMES, claim);
         return trashed;
@@ -458,31 +638,46 @@ function createDrive(deps) {
     },
     /** Items trashed on their own, newest first. */
     async listTrash(ctx) {
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
       const page = await store.query(NODES, { where: { owner: ctx.owner, trashed: true }, limit: 1e3 });
       const out = [];
-      for (const { data } of page.items) if (data.purging !== true && await can(ctx, "read", data)) out.push(data);
+      for (const { data } of page.items) if (data.purging !== true) out.push(data);
       return out.sort((a, b) => (b.trashedAt ?? 0) - (a.trashedAt ?? 0));
     },
     /** Puts a trashed item back. It needs a live parent folder. */
     async restore(ctx, id, opts = {}) {
+      let height = 0;
+      if (sharing && opts.parentId !== void 0) {
+        const probe = await fetch(store, ctx, id);
+        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);
         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 = await fetch(tx, ctx, opts.parentId ?? node.parentId);
-        if (!parent || parent.kind !== "folder" || !await isLive(tx, ctx, parent)) {
+        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)) {
           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 fitsUnder(tx, batch(), parent, height);
+        }
         let { name, key } = parseName(node.name);
-        if ((await claimed(tx, ctx.owner, parent.id, key)).taken) {
+        if ((await claimed(tx, parent.owner, parent.id, key)).taken) {
           if (opts.onConflict !== "rename") throw new DriveError("NAME_TAKEN", `"${name}" already exists`);
-          name = await freeName(tx, ctx, parent.id, name);
+          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(), updatedBy: who(ctx) };
+        const restored = { ...node, parentId: parent.id, name, nameKey: key, trashed: false, trashedAt: null, updatedAt: now(), ...stamp(ctx, node) };
         await tx.put(NODES, restored.id, restored);
-        await tx.put(NAMES, await claimId(ctx.owner, parent.id, key), { nodeId: restored.id, owner: ctx.owner, parentId: parent.id });
+        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));
         return restored;
       });
     },
@@ -503,6 +698,7 @@ function createDrive(deps) {
         if (q.minSize !== void 0 && node.size < q.minSize) continue;
         if (q.maxSize !== void 0 && node.size > q.maxSize) continue;
         if (q.createdByKind && node.createdBy.kind !== q.createdByKind) continue;
+        if (q.app !== void 0 && appOf(node) !== q.app) continue;
         hits.push({ node, path });
       }
       return hits.sort((a, b) => a.path < b.path ? -1 : 1).slice(0, limit);
@@ -520,15 +716,9 @@ function createDrive(deps) {
     },
     /** Deletes every item and blob of the owner for good. Only the owner may do this, never an agent for them. A failed call can run again. */
     async deleteAll(ctx) {
-      if (ctx.actor.kind !== "human" || ctx.actor.id !== ctx.owner) throw new DriveError("FORBIDDEN", "only the owner in person can delete the whole drive");
-      await need(ctx, "delete", rootNode(ctx));
-      let removed = 0;
-      for (let pass = 0; pass < 5; pass++) {
-        const all = await ownerNodes(ctx, true);
-        if (all.length === 0) return { removed };
-        removed += await removeNodes(all);
-      }
-      throw new DriveError("BUSY", "the drive kept changing while it was deleted. Run it again.");
+      assertInPerson(ctx, "delete the whole drive");
+      await need(ctx, "delete", rootNode(ctx.owner, ctx.actor));
+      return { removed: await eraseDrive(ctx.owner) };
     },
     /** Deletes a trashed item for good, with everything under it and all their bytes. */
     async purge(ctx, id) {
@@ -543,9 +733,233 @@ function createDrive(deps) {
         if (node.kind === "folder") queue.push(...await children(store, node.owner, node.id));
       }
       return { removed: await removeNodes(nodes, top) };
+    },
+    /**
+     * What the home view shows: every file and every reference to an app's document, newest change first.
+     * `apps` counts references per app, and `files` counts plain files, before `app` and `limit` apply.
+     */
+    async home(ctx, q = {}) {
+      const limit = q.limit ?? 100;
+      if (!Number.isInteger(limit) || limit < 1) throw new RangeError("limit must be an integer of 1 or more");
+      const all = await ownerNodes(ctx);
+      const byId = new Map(all.map((n) => [n.id, n]));
+      const apps = {};
+      let files = 0;
+      const items = [];
+      for (const node of all) {
+        const path = pathIn(byId, node, true);
+        if (path === null || node.kind === "folder") continue;
+        const app = appOf(node);
+        if (app === null) files++;
+        else apps[app] = (apps[app] ?? 0) + 1;
+        if (q.app === void 0 || app === q.app) items.push({ node, path, app });
+      }
+      items.sort((x, y) => y.node.updatedAt - x.node.updatedAt || (x.path < y.path ? -1 : 1));
+      return { items: items.slice(0, limit), apps, files };
+    },
+    /**
+     * An app puts one of its documents in this drive, as a reference such as `docs:<id>`. A document that is
+     * already in the drive comes back as it is, so an app can register again. The reference sits in `folder`
+     * (a path or a folder id, "/" by default) under `name`, and gets a free name when that one is taken.
+     */
+    async registerDocument(ctx, input) {
+      if (!REF.test(input.ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(input.ref)}`);
+      parseName(input.name);
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      const dir = input.folder ?? "/";
+      const owner = dir.startsWith("/") ? ctx.owner : (await resolve(store, ctx, dir.split("/")[0])).owner;
+      for (const { data } of await allWhere(store, NODES, { owner, ref: input.ref })) {
+        const node = data;
+        if (node.kind === "ref" && !node.trashed && node.purging !== true && await isLive(store, ctx, node) && await can(ctx, "read", node)) return node;
+      }
+      return api.putRef(ctx, dir.endsWith("/") ? `${dir}${input.name}` : `${dir}/${input.name}`, input.ref, { parents: true, onConflict: "rename" });
+    },
+    /** 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)}`);
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      let trashed = 0;
+      for (const { data } of await allWhere(store, NODES, { owner: ctx.owner, ref })) {
+        if (data.kind !== "ref" || data.trashed || data.purging === true) continue;
+        try {
+          await api.trash(ctx, data.id);
+          trashed++;
+        } catch (error) {
+          if (!(error instanceof DriveError && error.code === "TRASHED")) throw error;
+        }
+      }
+      return { trashed };
+    },
+    /**
+     * What drive holds about the person behind a call, besides their own drive (`exportData` has that). It is
+     * only for the person in person: an agent gets `partial: true` and nothing else. It holds the ids of the
+     * items they or their agents made or changed in other drives (no names, and nothing of the people who own
+     * them), the shares they hold, the invites they sent, and the audit entries of what they and their agents
+     * did. Invitee emails and link tokens are not in it.
+     */
+    async exportPerson(ctx) {
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      const subject = subjectOf(ctx);
+      if (!isInPerson(ctx)) return { subject, partial: true, authored: [], agents: [], shares: { held: [], invitesCreated: [] }, audit: [] };
+      const { actors, ownedAgents } = await actorsOf(store, subject.id);
+      const authored = (await madeBy(store, actors)).filter((n) => n.owner !== subject.id && n.purging !== true).map((n) => ({
+        id: n.id,
+        kind: n.kind,
+        created: actors.includes(n.createdById),
+        updated: actors.includes(n.updatedById),
+        createdAt: actors.includes(n.createdById) ? n.createdAt : null,
+        updatedAt: actors.includes(n.updatedById) ? n.updatedAt : null,
+        by: [...new Set([actors.includes(n.createdById) ? n.createdBy : null, actors.includes(n.updatedById) ? n.updatedBy : null].filter((a) => a !== null).map((a) => JSON.stringify(a)))].map((a) => JSON.parse(a))
+      })).sort((x, y) => x.id < y.id ? -1 : 1);
+      const held = [];
+      for (const actor of actors) for (const g of await allWhere(store, "grants", { subjectId: actor })) held.push({ subjectId: g.data.subjectId, resourceId: g.data.resourceId, role: g.data.role });
+      const agents = [];
+      for (const agent of ownedAgents) {
+        const items = (await rawOwnerNodes(agent, false)).map((n) => ({ id: n.id, kind: n.kind, name: n.name, size: n.size, mime: n.mime, createdAt: n.createdAt, updatedAt: n.updatedAt, trashed: n.trashed }));
+        agents.push({ id: agent, items });
+      }
+      const invitesCreated = [];
+      const audit = [];
+      for (const actor of actors) {
+        for (const i of await allWhere(store, "invites", { createdBy: actor })) {
+          invitesCreated.push({ id: i.data.id, resourceId: i.data.resourceId, role: i.data.role, expiresAt: i.data.expiresAt ?? null, accepted: i.data.acceptedAt !== void 0 });
+        }
+        for (const e of await allWhere(store, "audit", { principalId: actor }, { field: "at" })) {
+          audit.push({ at: e.data.at, action: e.data.action, resourceId: e.data.resourceId ?? null, outcome: e.data.outcome, principalId: e.data.principalId, principalKind: e.data.principalKind, machineMade: e.data.machineMade });
+        }
+      }
+      audit.sort((x, y) => x.at - y.at);
+      return { subject, partial: false, authored, agents, shares: { held, invitesCreated }, audit };
+    },
+    /**
+     * Erases a person for good. Only the person in person may. Their drive and its shares go. So do the shares
+     * they hold and the invites they or their agents sent, on drive items only: the grants of other apps stay for
+     * those apps and for identity. What they or their agents made in other drives stays, because it belongs to
+     * those drives: the id becomes "erased", and the kind stays, so machine-made work keeps its label. The audit
+     * trail stays: it holds ids and kinds only. A failed call can run again.
+     */
+    async erasePerson(ctx) {
+      assertInPerson(ctx, "erase a person");
+      const { id } = subjectOf(ctx);
+      const { actors, ownedAgents } = await actorsOf(store, id);
+      let { removed } = await api.deleteAll(ctx);
+      for (const agent of ownedAgents) removed += await eraseDrive(agent);
+      const ofDrive = async (docs) => {
+        const out = [];
+        for (const doc of docs) if ((await store.get("resources", doc.data.resourceId))?.type === "drive") out.push({ id: doc.id });
+        return out;
+      };
+      const sweep = async (docs, collection) => {
+        for (let i = 0; i < docs.length; i += 100) {
+          await transact(async (tx) => {
+            for (const doc of docs.slice(i, i + 100)) await tx.delete(collection, doc.id);
+          });
+        }
+        return docs.length;
+      };
+      let grants = 0;
+      let invites = 0;
+      for (const actor of actors) grants += await sweep(await ofDrive(await allWhere(store, "grants", { subjectId: actor })), "grants");
+      for (const actor of actors) invites += await sweep(await ofDrive(await allWhere(store, "invites", { createdBy: actor })), "invites");
+      const todo = await madeBy(store, actors);
+      for (let i = 0; i < todo.length; i += CHUNK) {
+        await transact(async (tx) => {
+          const current = [];
+          for (const node of todo.slice(i, i + CHUNK)) {
+            const found = await tx.get(NODES, node.id);
+            if (found) current.push(found);
+          }
+          for (const node of current) {
+            const next = { ...node };
+            if (actors.includes(node.createdById ?? node.createdBy.id)) Object.assign(next, { createdBy: { id: ERASED, kind: node.createdBy.kind }, createdById: ERASED });
+            if (actors.includes(node.updatedById ?? node.updatedBy.id)) Object.assign(next, { updatedBy: { id: ERASED, kind: node.updatedBy.kind }, updatedById: ERASED });
+            await tx.put(NODES, node.id, next);
+          }
+        });
+      }
+      return { removed, grants, invites, anonymized: todo.length };
+    },
+    /** Gives a person or an agent a role on an item and everything under it. Only an owner may. */
+    async shareWith(ctx, loc, subjectId, role) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      await viaSharing(ctx, (s, p) => s.grant(p, resource, subjectId, role));
+    },
+    async unshare(ctx, loc, subjectId) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      await viaSharing(ctx, (s, p) => s.revokeGrant(p, resource, subjectId));
+    },
+    /** Invite by `email` (a person) or `handle` (an agent). The invite lasts `expiresInMs`, if given. It sends no message. */
+    async invite(ctx, loc, input) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      return viaSharing(ctx, (s, p) => s.createInvite(p, resource, input));
+    },
+    /** `identity` is the verified email of a person, or the handle of an agent. */
+    async acceptInvite(ctx, inviteId, identity) {
+      await viaSharing(ctx, (s, p) => s.acceptInvite(p, inviteId, identity));
+    },
+    /** The token comes back once. Only its hash is stored. */
+    async createLink(ctx, loc, input) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      return viaSharing(ctx, (s, p) => s.createLink(p, resource, input));
+    },
+    async revokeLink(ctx, linkId) {
+      await viaSharing(ctx, (s, p) => s.revokeLink(p, linkId));
+    },
+    /** Who can reach an item, and by which links and invites. Only an owner may look. Link tokens are never shown. */
+    async shares(ctx, loc) {
+      const node = await resolve(store, ctx, loc);
+      await need(ctx, "delete", node);
+      const where = { resourceId: await resourceOf(node) };
+      const rows = async (collection) => (await store.query(collection, { where, limit: 100 })).items.map((item) => item.data);
+      return {
+        grants: (await rows("grants")).map((g) => ({ subjectId: g.subjectId, role: g.role })),
+        links: (await rows("links")).map((l) => ({ id: l.id, role: l.role, signedInOnly: l.signedInOnly === true, expiresAt: l.expiresAt ?? null, revoked: l.revokedAt != null })),
+        invites: (await rows("invites")).map((i) => ({ id: i.id, role: i.role, email: i.email ?? null, handle: i.handle ?? null, expiresAt: i.expiresAt ?? null, accepted: i.acceptedAt !== void 0 }))
+      };
+    },
+    openShared,
+    /** Live children of a folder that a link visitor or a signed-in person may read, sorted by name. */
+    async listShared(principal, id, linkToken) {
+      const folder = await openShared(principal, id, linkToken);
+      if (folder.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${folder.name} is not a folder`);
+      return (await children(store, folder.owner, folder.id)).filter((n) => !n.trashed && n.purging !== true).sort((x, y) => x.nameKey < y.nameKey ? -1 : x.nameKey > y.nameKey ? 1 : x.name < y.name ? -1 : 1);
+    },
+    async readShared(principal, id, linkToken) {
+      const node = await openShared(principal, id, linkToken);
+      if (node.kind !== "file" || !node.blobKey) throw new DriveError("NOT_A_FILE", `${node.name} is not a file`);
+      const blob = await blobs.get(node.blobKey);
+      if (!blob) throw new DriveError("BLOB_MISSING", `the bytes of ${node.name} are missing`);
+      return { node, ...blob };
     }
   };
-  return api;
+  async function viaSharing(ctx, fn) {
+    if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+    if (!ctx.principal) throw new DriveError("FORBIDDEN", "sign in to share");
+    try {
+      return await fn(sharing, ctx.principal);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "";
+      if (message === "forbidden") throw new DriveError("FORBIDDEN", "not allowed to share this item");
+      if (SHARE_ERROR.test(message)) throw new DriveError("INVALID_SHARE", message);
+      throw error;
+    }
+  }
+  async function prepare(ctx) {
+    if (!sharing || ctx.principal === void 0) return;
+    if (ctx.principal.chain[0]?.id !== ctx.owner) throw new DriveError("FORBIDDEN", "the caller does not own this drive");
+    const id = await rootResource(ctx.owner);
+    if ((await store.get("resources", id))?.type === "drive") return;
+    try {
+      await sharing.createResource(ctx.principal, { id, type: "drive" });
+    } catch {
+    }
+  }
+  const guarded = (call) => async (ctx, ...args) => {
+    await prepare(ctx);
+    return call(ctx, ...args);
+  };
+  const open = /* @__PURE__ */ new Set(["openShared", "listShared", "readShared"]);
+  return Object.fromEntries(Object.entries(api).map(([name, call]) => [name, open.has(name) ? call : guarded(call)]));
 }
 
 // src/zip.ts
@@ -674,7 +1088,8 @@ async function buildExport(drive, ctx, now = Date.now) {
       ...missing ? { missing: true } : {}
     };
   });
-  const manifest = { format: "agentic-drive-export", version: 1, exportedAt: now(), owner: ctx.owner, items };
+  const person = await drive.exportPerson(ctx);
+  const manifest = { format: "agentic-drive-export", version: 2, exportedAt: now(), owner: ctx.owner, subject: person.subject, partial: person.partial, items, authored: person.authored, agents: person.agents, shares: person.shares, audit: person.audit };
   return writeZip([{ name: "manifest.json", data: new TextEncoder().encode(JSON.stringify(manifest, null, 2)) }, ...entries], now());
 }
 
@@ -921,6 +1336,7 @@ export {
   DEFAULT_URL_SECONDS,
   safeMime,
   parseName,
+  rootResource,
   createDrive,
   writeZip,
   readZip,