agentic-drive 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.3.0
+
+Read the breaking changes before you upgrade. The migration steps follow them.
+
+### Breaking changes
+
+- **agentic-identity 0.4.0.** A grant has a kind and an id, and a person and an agent with the same id are two subjects. The range is now `^0.4.0`. Run identity's `migrateGrants` once on a store with grants from 0.3.0. See the migration steps.
+- **`shareWith` and `unshare` take a subject.** The subject is `{ kind: "human" | "agent", id }`, not a bare id. A subject with no kind, or with another kind, fails with `INVALID_SHARE`. The HTTP routes take `subjectKind` next to `subjectId`: in the body of `POST /shares`, and in the query of `DELETE /shares`. `GET /shares` lists `subjectKind` on each grant.
+- **Erase and export read grants by kind.** A person's erase and export touch the grants of that person and of their agents with their own identity. A grant of an agent with the same id as a person stays.
+
+### Added
+
+- **`agentic-drive/client`.** A typed client for the HTTP API: `createClient({ baseUrl, token, fetch?, retries? })`. It has one method for each bearer route and each shared route, a typed `DriveApiError` with the API `code` and the HTTP `status`, and `AbortSignal` support. It sends a write once. It uses only `fetch`.
+
+### Changed
+
+- A purge, `deleteAll`, and `erasePerson` erase each item and the drive root through identity's `deleteResource`. The grants, links, invites, and audit entries of the item go with it, so none survives the item. Before, the audit entries stayed. The shares go while the item is marked for erase, before its row goes, so a failed call leaves a marked item and the same call runs again. A caller who does not own the item, and an agent drive that `erasePerson` removes, get the same result from a sweep. A purge costs more calls for each item. Only the owner of the drive, in person, can finish a purge that failed after the shares were erased. An agent gets `NOT_FOUND` for that item.
+- New exports `subjectKindOf` and `parseSubject`. `subjectKindOf` accepts the kind of the root of a chain, `human` or `agent`, and throws on any other kind, a delegated one too.
+- An export lists `subjectKind` on each grant a person holds.
+
+### Migration
+
+Run the steps in this order. The old Worker keeps writing grants in the old format until step 3, so the migration in step 4 must come after the deploy.
+
+1. Install the new versions: `npm install agentic-drive@0.3.0 agentic-identity@^0.4.0`.
+2. Change every call of `shareWith` and `unshare` in your code to pass `{ kind, id }`. The build fails on a bare id, and a bare id in JavaScript fails with `INVALID_SHARE`.
+3. Deploy the 0.3.0 Worker. **From now until step 4, every owner loses access to their own drive.** Owner grants from before 0.3.0 are in the old format too, and identity 0.4.0 does not honor them. Everybody gets `NOT_FOUND`, and `erasePerson` and the export skip those grants. Run step 4 right after the deploy, or plan a maintenance window.
+4. Run `migrateGrants` in a one-off Worker set up as in the 0.2.0 steps. Add it to the `steps` of that Worker, for example `grants: (store) => migrateGrants(store)`, with `import { migrateGrants } from "agentic-identity"`. It rewrites grants that have no kind. If the call fails or runs out of time, call it again until `migrated` is 0. It skips what is done. Delete the one-off Worker after it.
+5. Delete from the `grants` collection each doc id that `migrateGrants` lists in `unresolved`. Its subject is gone, and identity never honors it. The share list leaves such a grant out.
+6. Change every HTTP client of `POST /shares` and `DELETE /shares` to send `subjectKind`. The new client does this.
+
 ## 0.2.0
 
 Read the breaking changes before you upgrade. The migration steps follow them.

package/README.md

@@ -66,7 +66,7 @@ every request. A missing, expired, or revoked credential, or a revoked or expire
 A session cookie is refused: only a bearer token counts. An agent acts in its owner's drive with the narrower scopes of its grant.
 Scopes are `drive:read`, `drive:write`, and `drive:admin`.
 
-Sharing routes: `GET /shares?path=`, `POST /shares`, `DELETE /shares?path=&subjectId=`, `POST /invites`,
+Sharing routes: `GET /shares?path=`, `POST /shares`, `DELETE /shares?path=&subjectId=&subjectKind=`, `POST /invites`,
 `POST /invites/accept`, `POST /links`, `DELETE /links?id=`. A link visitor reads with the header
 `x-link-token` on `GET /shared/:id`, `GET /shared/:id/items`, and `GET /shared/:id/content`.
 Name a shared item by its id. A path can start at a folder id: `<folder id>/notes/a.txt`.
@@ -74,6 +74,33 @@ Without `DRIVE_URL_SECRET` or `DRIVE_PUBLIC_URL`, every request gets 503.
 Create the R2 bucket with `--jurisdiction eu` and the D1 database with `--location weur`.
 The Worker declares region `eu` and refuses a D1 query that a non-EU region served. `DRIVE_REGION=unknown` turns this off for local runs.
 
+## SDK
+
+`agentic-drive/client` is a typed client for the HTTP API. It uses only `fetch`, so it runs in browsers, Workers, and Node 22.
+
+```ts
+import { createClient, DriveApiError } from "agentic-drive/client";
+
+const drive = createClient({ baseUrl: "https://drive.example.com", token: process.env.DRIVE_TOKEN });
+await drive.mkdir("/docs", { parents: true });
+const file = await drive.upload("/docs/a.txt", "hello", { mime: "text/plain" });
+const { data } = await drive.download(file.id);
+try {
+  await drive.stat("/missing");
+} catch (error) {
+  if (error instanceof DriveApiError) console.log(error.code, error.status); // NOT_FOUND 404
+}
+```
+
+- One method for each bearer route and each shared route: `list`, `stat`, `mkdir`, `upload`, `download`, `url`, `move`, `trash`, `listTrash`, `restore`, `purge`, `search`, `export`, `deleteAccount`, `home`, `registerDocument`, `forgetDocument`, `shares`, `share`, `unshare`, `invite`, `acceptInvite`, `createLink`, `revokeLink`, `openShared`, `listShared`, and `readShared`.
+- Each method has typed input and output. The client checks the shape of every answer, and `download` checks the bytes against their hash (it needs WebCrypto). `readShared` does not: the Worker sends no hash there. An answer that fails a check throws `BAD_RESPONSE`. `url` gives a signed link that you fetch yourself. The last argument takes `{ signal }` to stop the call with an `AbortSignal`.
+- A failed call throws `DriveApiError`. It has the `code` of the API and the HTTP `status`. A call that gets no answer has the code `NETWORK_ERROR` and status 0. An abort stays the abort error of `fetch`. A code that the client does not know gives `BAD_RESPONSE`.
+- The client never sends a write again. `retries` (default 0) sends a read (GET) again after a network error or a 502, 503, or 504, with a short wait. A redirect is an error (`BAD_RESPONSE`, with the status of the redirect, or 0 in a browser): set `baseUrl` to the final URL.
+- `fetch` is an option, for tests and for runtimes with their own. `openShared`, `listShared`, and `readShared` work without a token, with a `linkToken`.
+- A stream body for `upload` is refused by some browsers. The error says so, and nothing is sent. Items from before 0.2.0 need `backfillAuthorIds`, and grants from before 0.3.0 need identity's `migrateGrants`. Without them, an answer that holds one fails with `BAD_RESPONSE`.
+- A browser page needs the Worker on its own origin for now: the Worker sends no CORS headers.
+- Share with a subject: `share("/pub", { kind: "human", id: "u2" }, "viewer")`.
+
 ## Features
 
 - Folders, files, and typed references to documents in other apps (`docs:<id>`).
@@ -83,14 +110,14 @@ The Worker declares region `eu` and refuses a D1 query that a non-EU region serv
 - Each item records its size, type, owner, and who made and last changed it, with the actor kind.
 - Storage sits behind the `Store` and `Blobs` ports of `agentic-identity`. Tests use its memory adapters. The CLI uses a local file adapter that passes the same contract suites. The Worker uses its D1 and R2 adapters.
 - Roles: viewer, commenter, editor, owner. A role on a folder reaches everything under it, and follows an item that moves. Identity decides every request through `can()`, which also writes the audit entry. A caller who cannot read an item gets `NOT_FOUND`. A caller who can read it but not change it gets `FORBIDDEN`. Editors write and trash. An item takes the roles of its new folder, so moving an item into a folder where the caller is owner needs owner on the item. Only owners share, purge, and read the share list.
-- Share by person or agent id, by invite (an email for a person, a handle for an agent), or by link with a role, an expiry, and an optional sign-in. The SDK calls are `shareWith`, `unshare`, `invite`, `acceptInvite`, `createLink`, `revokeLink`, `shares`, `openShared`, `listShared`, and `readShared`.
+- Share by a subject (`{ kind: "human" | "agent", id }`), by invite (an email for a person, a handle for an agent), or by link with a role, an expiry, and an optional sign-in. The SDK calls are `shareWith`, `unshare`, `invite`, `acceptInvite`, `createLink`, `revokeLink`, `shares`, `openShared`, `listShared`, and `readShared`.
 - Two live items never share a name in one folder. A claim document holds each name. It is written in the same transaction as the item, and it is deleted when the item goes to the trash.
 - `upload()` reads a stream with a size cap, finds the type from the first bytes, and stores a SHA-256 hash.
 - `downloadUrl()` returns a signed URL. The URL signs an attachment header with the file name and the stored type. The Worker verifies it and serves the bytes with those headers, so the link holder cannot change how the bytes are served. A link lasts 15 minutes by default and 1 hour at most. Trashing a file does not revoke a link already issued.
 - `search()` finds live items by name, type, kind, size, and who made them.
 - App documents: an app calls `registerDocument({ ref: "docs:<id>", name, folder })` to put a document in the drive, and `forgetDocument(ref)` when it deletes the document. `home({ app })` lists files and every app's documents together, newest change first, with a count per app. `search({ app })` filters the same way. The CLI has `home`, `register`, and `forget`. The MCP server has `drive_home`, `drive_register_document`, and `drive_forget_document`.
 - `buildExport()` writes everything one person has to a zip with a `manifest.json` (format version 2). It names the person by id and kind. It lists the person's own items (trashed ones are flagged, and a file whose bytes are gone is marked `missing`). For the person in person it also lists the ids of what 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. An agent gets `partial: true` and none of that. Invitee emails and link tokens are never in it. Entries are named by item id.
-- `erasePerson()` erases a person for good, and only the person in person can call it (the CLI `delete-all` and `DELETE /account` call it). It deletes their drive with all its shares, 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. Agents are found through the `principals` collection, as identity finds them: an agent with its own identity names the person as `ownerId`, and a delegated agent names its parent. An agent with its own identity belongs to the person, and so does its drive: erase deletes it, and the export lists its items (no bytes). A person with more than 1000 agents cannot be erased here: the call fails and deletes nothing more. The audit trail stays: it holds ids and kinds only. A failed call can run again. `deleteAll()` is the drive part alone.
+- `erasePerson()` erases a person for good, and only the person in person can call it (the CLI `delete-all` and `DELETE /account` call it). It deletes their drive with all its shares, 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. Agents are found through the `principals` collection, as identity finds them: an agent with its own identity names the person as `ownerId`, and a delegated agent names its parent. An agent with its own identity belongs to the person, and so does its drive: erase deletes it, and the export lists its items (no bytes). A person with more than 1000 agents cannot be erased here: the call fails and deletes nothing more. The audit entries of the erased items go with them, through identity `deleteResource`. The entries about what the person did in other drives stay: they hold ids and kinds only. A failed call can run again. `deleteAll()` is the drive part alone.
 - A `can()` hook decides who may read, write, or delete. Without `sharing`, the default allows the owner only.
 
 ## Limits

package/SKILL.md

@@ -18,6 +18,17 @@ const me = { owner: "u1", actor: { id: "u1", kind: "human" } };
 await drive.mkdir(me, "/notes");
 ```
 
+To call a deployed Worker, use the remote client. It runs in browsers, Workers, and Node 22:
+
+```js
+import { createClient } from "agentic-drive/client";
+
+const remote = createClient({ baseUrl: "https://drive.example.com", token });
+await remote.mkdir("/notes");
+```
+
+A failed call throws `DriveApiError`. Read its `code` and `status`.
+
 ## Rules
 
 - A locator with a `/` is a path: `/x` from the root, or `<folder id>/x` from a folder. Any other locator is an id.

package/dist/{chunk-3LISWG7H.js → chunk-5KEISBS4.js}

@@ -1,7 +1,7 @@
 import {
   ROOT_ID,
   rootResource
-} from "./chunk-6CWBHSJ7.js";
+} from "./chunk-VSVIJBMJ.js";
 
 // src/migrate.ts
 var PAGE = 10;

package/dist/{chunk-RWMBGIAS.js → chunk-GMA5I5L6.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.2.0" : readPackageVersion();
+var VERSION = true ? "0.3.0" : readPackageVersion();
 
 export {
   VERSION

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

@@ -1,5 +1,5 @@
 // src/drive.ts
-import { MAX_FOLDER_DEPTH } from "agentic-identity";
+import { EraseRefusedError, MAX_FOLDER_DEPTH, SUBJECT_KINDS } from "agentic-identity";
 var ROOT_ID = "root";
 var NODES = "drive_nodes";
 var NAMES = "drive_names";
@@ -80,6 +80,17 @@ 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";
+function subjectKindOf(kind) {
+  if (kind === "human" || kind === "agent") return kind;
+  throw new DriveError("INVALID_SHARE", `a ${typeof kind === "string" ? kind : "missing"} principal cannot hold a role. Only the root of a chain can: human or agent`);
+}
+function parseSubject(input) {
+  const s = input;
+  if (!s || typeof s.id !== "string" || s.id === "" || !SUBJECT_KINDS.includes(s.kind)) {
+    throw new DriveError("INVALID_SHARE", `a subject needs an id and a kind (${SUBJECT_KINDS.join(" or ")})`);
+  }
+  return { kind: s.kind, id: s.id };
+}
 var SHARE_ERROR = /^(invalid|give an|expiresAt|expiresInMs|resource exists|the last owner)/;
 function createDrive(deps) {
   const { store, blobs } = deps;
@@ -393,6 +404,7 @@ function createDrive(deps) {
     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) });
+  const heldBy = (who2, ownedAgents) => [[who2.id, subjectKindOf(who2.kind)], ...ownedAgents.map((a) => [a, subjectKindOf("agent")])];
   async function allWhere(ops, collection, where, orderBy) {
     const out = [];
     for (let cursor; ; ) {
@@ -419,23 +431,39 @@ function createDrive(deps) {
     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) {
+  async function eraseDrive(owner, principal) {
     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);
-        });
+        await finishResource(principal, await rootResource(owner));
         return removed;
       }
-      removed += await removeNodes(all);
+      removed += await removeNodes(all, void 0, principal);
     }
     throw new DriveError("BUSY", "the drive kept changing while it was deleted. Run it again.");
   }
+  async function finishResource(principal, resourceId) {
+    if (!sharing) return;
+    if (principal) {
+      try {
+        await sharing.deleteResource(principal, resourceId);
+        return;
+      } catch (error) {
+        if (!(error instanceof EraseRefusedError) && !(error instanceof Error && error.message === "forbidden")) throw error;
+      }
+    }
+    await transact(async (tx) => {
+      for (const share of await sharesOf(tx, resourceId)) await tx.delete(share.collection, share.id);
+      await tx.delete("resources", resourceId);
+    });
+    for (let cursor; ; ) {
+      const page = await store.query("audit", { where: { resourceId }, limit: 100, cursor });
+      for (const entry of page.items) await store.delete("audit", entry.id);
+      if (!page.nextCursor) break;
+      cursor = page.nextCursor;
+    }
+  }
   async function sharesOf(ops, resourceId) {
     const out = [];
     for (const collection of ["grants", "links", "invites"]) {
@@ -448,7 +476,7 @@ function createDrive(deps) {
     }
     return out;
   }
-  async function removeNodes(nodes, top) {
+  async function removeNodes(nodes, top, principal) {
     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 = [];
@@ -486,18 +514,16 @@ function createDrive(deps) {
     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);
+      for (const node of chunk) await finishResource(principal, node.id);
       await transact(async (tx) => {
         const held = [];
         for (const node of chunk) {
           const claim = node.trashed ? null : await claimId(node.owner, node.parentId, node.nameKey);
-          const shares = sharing ? await sharesOf(tx, node.id) : [];
-          held.push({ node, claim, owns: claim !== null && (await tx.get(NAMES, claim))?.nodeId === node.id, shares });
+          held.push({ node, claim, owns: claim !== null && (await tx.get(NAMES, claim))?.nodeId === node.id });
         }
-        for (const { node, claim, owns, shares } of held) {
+        for (const { node, claim, owns } 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);
         }
       });
     }
@@ -718,21 +744,23 @@ function createDrive(deps) {
     async deleteAll(ctx) {
       assertInPerson(ctx, "delete the whole drive");
       await need(ctx, "delete", rootNode(ctx.owner, ctx.actor));
-      return { removed: await eraseDrive(ctx.owner) };
+      return { removed: await eraseDrive(ctx.owner, ctx.principal) };
     },
     /** Deletes a trashed item for good, with everything under it and all their bytes. */
     async purge(ctx, id) {
-      const top = await fetch(store, ctx, id, true);
+      const marked = await rawNode(store, id, ctx.owner, ctx.actor, true);
+      const resumed = marked?.purging === true && sharing !== void 0 && isInPerson(ctx) && marked.owner === ctx.owner && await store.get("resources", marked.id) === null;
+      const top = resumed ? marked : await fetch(store, ctx, id, true);
       if (!top || top.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
       if (!top.trashed) throw new DriveError("NOT_TRASHED", `${top.name} is not in the trash`);
-      await need(ctx, "delete", top);
+      if (!resumed) await need(ctx, "delete", top);
       const nodes = [];
       for (const queue = [top]; queue.length; ) {
         const node = queue.pop();
         nodes.push(node);
         if (node.kind === "folder") queue.push(...await children(store, node.owner, node.id));
       }
-      return { removed: await removeNodes(nodes, top) };
+      return { removed: await removeNodes(nodes, top, ctx.principal) };
     },
     /**
      * What the home view shows: every file and every reference to an app's document, newest change first.
@@ -812,7 +840,7 @@ function createDrive(deps) {
         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 });
+      for (const [actor, kind] of heldBy(subject, ownedAgents)) for (const g of await allWhere(store, "grants", { subjectId: actor, subjectKind: kind })) held.push({ subjectKind: g.data.subjectKind, 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 }));
@@ -836,7 +864,7 @@ function createDrive(deps) {
      * 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.
+     * entries of the erased items go with them. The ones about what the person did in other drives stay: they hold ids and kinds only. A failed call can run again.
      */
     async erasePerson(ctx) {
       assertInPerson(ctx, "erase a person");
@@ -859,7 +887,7 @@ function createDrive(deps) {
       };
       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, kind] of heldBy(subjectOf(ctx), ownedAgents)) grants += await sweep(await ofDrive(await allWhere(store, "grants", { subjectId: actor, subjectKind: kind })), "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) {
@@ -880,13 +908,13 @@ function createDrive(deps) {
       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) {
+    async shareWith(ctx, loc, subject, role) {
       const resource = await resourceOf(await resolve(store, ctx, loc));
-      await viaSharing(ctx, (s, p) => s.grant(p, resource, subjectId, role));
+      await viaSharing(ctx, (s, p) => s.grant(p, resource, parseSubject(subject), role));
     },
-    async unshare(ctx, loc, subjectId) {
+    async unshare(ctx, loc, subject) {
       const resource = await resourceOf(await resolve(store, ctx, loc));
-      await viaSharing(ctx, (s, p) => s.revokeGrant(p, resource, subjectId));
+      await viaSharing(ctx, (s, p) => s.revokeGrant(p, resource, parseSubject(subject)));
     },
     /** Invite by `email` (a person) or `handle` (an agent). The invite lasts `expiresInMs`, if given. It sends no message. */
     async invite(ctx, loc, input) {
@@ -912,7 +940,8 @@ function createDrive(deps) {
       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 })),
+        // A grant with no valid kind is from before 0.4.0 and not migrated. Identity does not honor it, so the list leaves it out.
+        grants: (await rows("grants")).filter((g) => SUBJECT_KINDS.includes(g.subjectKind)).map((g) => ({ subjectKind: g.subjectKind, 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 }))
       };
@@ -1337,6 +1366,8 @@ export {
   safeMime,
   parseName,
   rootResource,
+  subjectKindOf,
+  parseSubject,
   createDrive,
   writeZip,
   readZip,

package/dist/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-GMA5I5L6.js";
 import {
   DriveError,
   buildExport,
   openLocal,
   publicNode,
   upload
-} from "./chunk-6CWBHSJ7.js";
+} from "./chunk-VSVIJBMJ.js";
 
 // src/cli.ts
 import { createReadStream, realpathSync, writeFileSync } from "fs";

package/dist/client.d.ts

@@ -0,0 +1,173 @@
+import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-Dlzwukjq.js';
+import 'agentic-identity';
+
+type Role = "viewer" | "commenter" | "editor" | "owner";
+type OnConflict = "fail" | "rename" | "replace";
+type SubjectKind = "human" | "agent";
+type Subject = {
+    kind: SubjectKind;
+    id: string;
+};
+/** An item as the API prints it: no storage keys. */
+type Item = Omit<Node, "nameKey" | "blobKey" | "purging">;
+/** A search hit, or a home item: an item with its path. */
+type PathItem = Item & {
+    path: string;
+};
+/** The codes of the drive, and the ones that only the Worker raises. */
+type ApiErrorCode = ErrorCode | "UNAUTHORIZED" | "NOT_CONFIGURED" | "INVALID_LINK" | "INTERNAL";
+/** `NETWORK_ERROR` means no answer came (status 0). `BAD_RESPONSE` means an answer that is not the API's. */
+type ClientErrorCode = ApiErrorCode | "NETWORK_ERROR" | "BAD_RESPONSE";
+/** The error of every failed call. `code` is the code of the API, and `status` is the HTTP status. */
+declare class DriveApiError extends Error {
+    readonly code: ClientErrorCode;
+    readonly status: number;
+    constructor(code: ClientErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** The origin of the Worker, such as `https://drive.example.com`. */
+    baseUrl: string;
+    /** A bearer token. It is optional only for the link routes, `openShared`, `listShared`, and `readShared`. */
+    token?: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** How often a read (GET) call tries again after a network error or a 502, 503, or 504. The default is 0. A write is never tried again. */
+    retries?: number;
+}
+interface CallOptions {
+    signal?: AbortSignal;
+}
+type UploadBody = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+interface Downloaded {
+    data: Uint8Array;
+    contentType: string;
+    sha256: string;
+}
+declare function createClient(options: ClientOptions): {
+    /** The live items of a folder. */
+    list: (path?: string, o?: CallOptions) => Promise<Item[]>;
+    stat: (path: string, o?: CallOptions) => Promise<Item>;
+    mkdir: (path: string, opts?: {
+        parents?: boolean;
+    }, o?: CallOptions) => Promise<Item>;
+    /** Writes a file. A `ReadableStream` body streams in runtimes that allow it. */
+    upload: (path: string, body: UploadBody, opts?: {
+        mime?: string;
+        parents?: boolean;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
+    /** The bytes. They are checked against the hash that the server sends. */
+    download: (path: string, o?: CallOptions) => Promise<Downloaded>;
+    /** A signed link that works without a token, for `expires` seconds. You fetch the link yourself. */
+    url: (path: string, expires?: number, o?: CallOptions) => Promise<{
+        url: string;
+        expiresInSeconds: number;
+    }>;
+    move: (src: string, folder: string, opts?: {
+        name?: string;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
+    trash: (path: string, o?: CallOptions) => Promise<Item>;
+    listTrash: (o?: CallOptions) => Promise<Item[]>;
+    restore: (itemId: string, opts?: {
+        parentId?: string;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
+    /** Deletes a trashed item for good. */
+    purge: (itemId: string, o?: CallOptions) => Promise<{
+        removed: number;
+    }>;
+    search: (q?: Pick<SearchQuery, "name" | "mime" | "kind" | "minSize" | "maxSize" | "createdByKind" | "app" | "limit">, o?: CallOptions) => Promise<PathItem[]>;
+    /** Everything the caller has, as a zip. */
+    export: (o?: CallOptions) => Promise<Uint8Array<ArrayBufferLike>>;
+    /** Erases the caller for good. The client sends `confirm=yes`. */
+    deleteAccount: (o?: CallOptions) => Promise<{
+        removed: number;
+        grants: number;
+        invites: number;
+        anonymized: number;
+    }>;
+    home: (q?: {
+        app?: string;
+        limit?: number;
+    }, o?: CallOptions) => Promise<{
+        apps: Record<string, number>;
+        files: number;
+        items: (PathItem & {
+            app: string | null;
+        })[];
+    }>;
+    registerDocument: (input: {
+        ref: string;
+        name: string;
+        folder?: string;
+    }, o?: CallOptions) => Promise<Item>;
+    forgetDocument: (ref: string, o?: CallOptions) => Promise<{
+        trashed: number;
+    }>;
+    shares: (path: string, o?: CallOptions) => Promise<{
+        grants: {
+            subjectKind: SubjectKind;
+            subjectId: string;
+            role: Role;
+        }[];
+        links: {
+            id: string;
+            role: Role;
+            signedInOnly: boolean;
+            expiresAt: number | null;
+            revoked: boolean;
+        }[];
+        invites: {
+            id: string;
+            role: Role;
+            email: string | null;
+            handle: string | null;
+            expiresAt: number | null;
+            accepted: boolean;
+        }[];
+    }>;
+    share: (path: string, subject: Subject, role: Role, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    unshare: (path: string, subject: Subject, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** Invite by `email` (a person) or `handle` (an agent). It sends no message. */
+    invite: (path: string, input: {
+        role: Role;
+        email?: string;
+        handle?: string;
+        expiresInMs?: number;
+    }, o?: CallOptions) => Promise<{
+        id: string;
+    }>;
+    acceptInvite: (inviteId: string, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** The token of a link comes back once. */
+    createLink: (path: string, input: {
+        role: Role;
+        expiresInMs?: number;
+        signedInOnly?: boolean;
+    }, o?: CallOptions) => Promise<{
+        id: string;
+        token: string;
+    }>;
+    revokeLink: (linkId: string, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** The next three read a shared item by id. Pass a link token, a bearer token, or both. */
+    openShared: (itemId: string, opts?: {
+        linkToken?: string;
+    } & CallOptions) => Promise<Item>;
+    listShared: (itemId: string, opts?: {
+        linkToken?: string;
+    } & CallOptions) => Promise<Item[]>;
+    readShared: (itemId: string, opts?: {
+        linkToken?: string;
+    } & CallOptions) => Promise<Omit<Downloaded, "sha256">>;
+};
+type DriveClient = ReturnType<typeof createClient>;
+
+export { type ApiErrorCode, type CallOptions, type ClientErrorCode, type ClientOptions, type Downloaded, DriveApiError, type DriveClient, type Item, type OnConflict, type PathItem, type Role, type Subject, type SubjectKind, type UploadBody, createClient };

package/dist/client.js

@@ -0,0 +1,240 @@
+// src/client.ts
+var DriveApiError = class extends Error {
+  constructor(code, status, message) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "DriveApiError";
+  }
+  code;
+  status;
+};
+var BASE = "/api/v1/drive";
+var CODES = {
+  NOT_FOUND: true,
+  NAME_TAKEN: true,
+  BLOB_EXISTS: true,
+  INVALID_NAME: true,
+  INVALID_PATH: true,
+  INVALID_REF: true,
+  NOT_A_FOLDER: true,
+  NOT_A_FILE: true,
+  MOVE_INTO_SELF: true,
+  TOO_DEEP: true,
+  PARENT_GONE: true,
+  TRASHED: true,
+  NOT_TRASHED: true,
+  IS_ROOT: true,
+  FORBIDDEN: true,
+  BLOB_MISSING: true,
+  TOO_LARGE: true,
+  INVALID_EXPIRY: true,
+  BUSY: true,
+  CROSS_DRIVE: true,
+  INVALID_SHARE: true,
+  TOO_MANY_ITEMS: true,
+  UNAUTHORIZED: true,
+  NOT_CONFIGURED: true,
+  INVALID_LINK: true,
+  INTERNAL: true
+};
+var KNOWN_CODES = new Set(Object.keys(CODES));
+var record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var text = (v) => typeof v === "string";
+var orNull = (test) => (v) => v === null || test(v);
+var num = (v) => typeof v === "number";
+var ACTOR_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+var ROLES = ["viewer", "commenter", "editor", "owner"];
+var oneOf = (list) => (v) => typeof v === "string" && list.includes(v);
+var actor = (v) => record(v) && text(v.id) && oneOf(ACTOR_KINDS)(v.kind);
+var isItem = (v) => record(v) && text(v.id) && text(v.owner) && text(v.parentId) && text(v.name) && (v.kind === "folder" || v.kind === "file" || v.kind === "ref") && num(v.size) && orNull(text)(v.mime) && orNull(text)(v.hash) && orNull(text)(v.ref) && num(v.createdAt) && num(v.updatedAt) && actor(v.createdBy) && actor(v.updatedBy) && text(v.createdById) && text(v.updatedById) && typeof v.trashed === "boolean" && orNull(num)(v.trashedAt);
+var isPathItem = (v) => isItem(v) && typeof v.path === "string";
+var listOf = (check) => (v) => Array.isArray(v) && v.every(check);
+var shape = (test) => (v) => record(v) && test(v);
+var numbers = (...keys) => shape((v) => keys.every((k) => typeof v[k] === "number"));
+var isOk = shape((v) => v.ok === true);
+var RETRY_STATUS = /* @__PURE__ */ new Set([502, 503, 504]);
+function createClient(options) {
+  let origin;
+  try {
+    const url = new URL(options.baseUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("not http");
+    origin = url.origin;
+  } catch {
+    throw new TypeError("baseUrl must be an http or https URL");
+  }
+  const { token } = options;
+  if (token !== void 0 && (typeof token !== "string" || !/^[A-Za-z0-9_-]{1,512}$/.test(token))) throw new TypeError("token must be 1 to 512 letters, digits, - or _");
+  const retries = options.retries ?? 0;
+  if (!Number.isInteger(retries) || retries < 0 || retries > 5) throw new RangeError("retries must be an integer from 0 to 5");
+  const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const query = (params) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) if (value !== void 0) search.set(key, String(value));
+    const text2 = search.toString();
+    return text2 === "" ? "" : `?${text2}`;
+  };
+  async function send(method, path, init) {
+    if (init.auth !== false && token === void 0) throw new TypeError("this call needs a token");
+    const headers = { ...token === void 0 ? {} : { authorization: `Bearer ${token}` }, ...init.headers };
+    let body = init.body;
+    if (init.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.json);
+    }
+    const attempts = method === "GET" ? retries + 1 : 1;
+    for (let attempt = 1; ; attempt++) {
+      let response;
+      try {
+        response = await doFetch(`${origin}${BASE}${path}`, { method, headers, body, signal: init.signal, redirect: "manual", ...body instanceof ReadableStream ? { duplex: "half" } : {} });
+      } catch (error) {
+        if (init.signal?.aborted || error instanceof Error && error.name === "AbortError") throw error;
+        if (attempt < attempts) {
+          await pause(attempt, init.signal);
+          continue;
+        }
+        const refused = body instanceof ReadableStream ? " (a stream body may be refused by this runtime: send bytes)" : "";
+        throw new DriveApiError("NETWORK_ERROR", 0, `${error instanceof Error ? `no answer: ${error.message}` : "no answer"}${refused}`);
+      }
+      if (attempt < attempts && RETRY_STATUS.has(response.status)) {
+        await response.body?.cancel();
+        await pause(attempt, init.signal);
+        continue;
+      }
+      if (response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new DriveApiError("BAD_RESPONSE", response.status, "the server redirected. Set baseUrl to the final URL.");
+      }
+      if (response.ok) return response;
+      throw await errorOf(response, init.signal);
+    }
+  }
+  async function pause(attempt, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", stop);
+        resolve();
+      }, Math.min(100 * 2 ** (attempt - 1), 1e3));
+      const stop = () => {
+        clearTimeout(timer);
+        reject(signal?.reason);
+      };
+      signal?.addEventListener("abort", stop, { once: true });
+    });
+  }
+  async function errorOf(response, signal) {
+    let code = "BAD_RESPONSE";
+    let message = `the server answered ${response.status}`;
+    try {
+      const parsed = await response.json();
+      if (typeof parsed.error?.code === "string" && KNOWN_CODES.has(parsed.error.code)) code = parsed.error.code;
+      else if (typeof parsed.error?.code === "string") message = `the server answered ${response.status} with an unknown code, ${JSON.stringify(parsed.error.code.slice(0, 40))}`;
+      if (code !== "BAD_RESPONSE" && typeof parsed.error?.message === "string") message = parsed.error.message;
+    } catch (error) {
+      if (signal?.aborted) throw error;
+    }
+    return new DriveApiError(code, response.status, message);
+  }
+  async function json(method, path, init, check) {
+    const response = await send(method, path, init);
+    let value;
+    try {
+      value = await response.json();
+    } catch (error) {
+      if (init.signal?.aborted) throw error;
+      if (!(error instanceof SyntaxError)) throw new DriveApiError("NETWORK_ERROR", 0, "the connection dropped while the body came in");
+      throw new DriveApiError("BAD_RESPONSE", response.status, "the answer is not JSON");
+    }
+    if (!check(value)) throw new DriveApiError("BAD_RESPONSE", response.status, "the answer is not the shape that the API sends");
+    return value;
+  }
+  async function bytes(path, init, verify = false) {
+    const response = await send("GET", path, init);
+    let data;
+    try {
+      data = new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      if (init.signal?.aborted) throw error;
+      throw new DriveApiError("NETWORK_ERROR", 0, "the connection dropped while the body came in");
+    }
+    const sha256 = response.headers.get("x-content-sha256") ?? "";
+    if (verify) {
+      if (!/^[0-9a-f]{64}$/.test(sha256)) throw new DriveApiError("BAD_RESPONSE", response.status, "the answer has no valid x-content-sha256");
+      if (typeof crypto === "undefined" || !crypto.subtle) throw new DriveApiError("BAD_RESPONSE", response.status, "this runtime has no WebCrypto, so the bytes cannot be checked. Use https.");
+      const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", data));
+      if (Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("") !== sha256) throw new DriveApiError("BAD_RESPONSE", response.status, "the bytes do not match their hash");
+    }
+    return { data, contentType: response.headers.get("content-type") ?? "application/octet-stream", sha256 };
+  }
+  const link = (token2) => {
+    if (token2 === void 0) return void 0;
+    if (!/^[A-Za-z0-9_-]{1,512}$/.test(token2)) throw new TypeError("a link token has 1 to 512 letters, digits, - or _");
+    return { "x-link-token": token2 };
+  };
+  const id = (value) => {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/.test(value) || value === "." || value === "..") throw new TypeError("an item id has letters, digits, -, _ and . (not first), and is not . or ..");
+    return value;
+  };
+  const isUrl = shape((v) => typeof v.url === "string" && /^https?:\/\//.test(v.url) && URL.canParse(v.url) && typeof v.expiresInSeconds === "number");
+  const isShares = shape(
+    (v) => listOf(shape((g) => (g.subjectKind === "human" || g.subjectKind === "agent") && text(g.subjectId) && oneOf(ROLES)(g.role)))(v.grants) && listOf(shape((l) => text(l.id) && oneOf(ROLES)(l.role) && typeof l.signedInOnly === "boolean" && orNull(num)(l.expiresAt) && typeof l.revoked === "boolean"))(v.links) && listOf(shape((i) => text(i.id) && oneOf(ROLES)(i.role) && orNull(text)(i.email) && orNull(text)(i.handle) && orNull(num)(i.expiresAt) && typeof i.accepted === "boolean"))(v.invites)
+  );
+  const isHome = shape((v) => record(v.apps) && Object.values(v.apps).every(num) && num(v.files) && listOf(shape((i) => isPathItem(i) && orNull(text)(i.app)))(v.items));
+  const isId = shape((v) => typeof v.id === "string");
+  const isLink = shape((v) => typeof v.id === "string" && typeof v.token === "string");
+  return {
+    /** The live items of a folder. */
+    list: (path = "/", o = {}) => json("GET", `/items${query({ path })}`, o, listOf(isItem)),
+    stat: (path, o = {}) => json("GET", `/stat${query({ path })}`, o, isItem),
+    mkdir: (path, opts = {}, o = {}) => json("POST", "/folders", { json: { path, parents: opts.parents === true }, ...o }, isItem),
+    /** Writes a file. A `ReadableStream` body streams in runtimes that allow it. */
+    upload: (path, body, opts = {}, o = {}) => json("PUT", `/files${query({ path, mime: opts.mime, parents: opts.parents === true ? true : void 0, onConflict: opts.onConflict })}`, {
+      body: typeof body === "string" ? new TextEncoder().encode(body) : body,
+      headers: { "content-type": "application/octet-stream" },
+      ...o
+    }, isItem),
+    /** The bytes. They are checked against the hash that the server sends. */
+    download: (path, o = {}) => bytes(`/files${query({ path })}`, o, true),
+    /** A signed link that works without a token, for `expires` seconds. You fetch the link yourself. */
+    url: (path, expires, o = {}) => json("GET", `/url${query({ path, expires })}`, o, isUrl),
+    move: (src, folder, opts = {}, o = {}) => json("POST", "/move", { json: { src, folder, ...opts }, ...o }, isItem),
+    trash: (path, o = {}) => json("POST", "/trash", { json: { path }, ...o }, isItem),
+    listTrash: (o = {}) => json("GET", "/trash", o, listOf(isItem)),
+    restore: (itemId, opts = {}, o = {}) => json("POST", "/restore", { json: { id: itemId, ...opts }, ...o }, isItem),
+    /** Deletes a trashed item for good. */
+    purge: (itemId, o = {}) => json("POST", "/purge", { json: { id: itemId }, ...o }, numbers("removed")),
+    search: (q = {}, o = {}) => json("GET", `/search${query(q)}`, o, listOf(isPathItem)),
+    /** Everything the caller has, as a zip. */
+    export: async (o = {}) => {
+      const { data } = await bytes("/export", o);
+      if (data[0] !== 80 || data[1] !== 75) throw new DriveApiError("BAD_RESPONSE", 200, "the answer is not a zip");
+      return data;
+    },
+    /** Erases the caller for good. The client sends `confirm=yes`. */
+    deleteAccount: (o = {}) => json("DELETE", "/account?confirm=yes", o, numbers("removed", "grants", "invites", "anonymized")),
+    home: (q = {}, o = {}) => json("GET", `/home${query(q)}`, o, isHome),
+    registerDocument: (input, o = {}) => json("POST", "/documents", { json: input, ...o }, isItem),
+    forgetDocument: (ref, o = {}) => json("DELETE", `/documents${query({ ref })}`, o, numbers("trashed")),
+    shares: (path, o = {}) => json("GET", `/shares${query({ path })}`, o, isShares),
+    share: (path, subject, role, o = {}) => json("POST", "/shares", { json: { path, subjectId: subject.id, subjectKind: subject.kind, role }, ...o }, isOk),
+    unshare: (path, subject, o = {}) => json("DELETE", `/shares${query({ path, subjectId: subject.id, subjectKind: subject.kind })}`, o, isOk),
+    /** Invite by `email` (a person) or `handle` (an agent). It sends no message. */
+    invite: (path, input, o = {}) => json("POST", "/invites", { json: { path, ...input }, ...o }, isId),
+    acceptInvite: (inviteId, o = {}) => json("POST", "/invites/accept", { json: { id: inviteId }, ...o }, isOk),
+    /** The token of a link comes back once. */
+    createLink: (path, input, o = {}) => json("POST", "/links", { json: { path, ...input }, ...o }, isLink),
+    revokeLink: (linkId, o = {}) => json("DELETE", `/links${query({ id: linkId })}`, o, isOk),
+    /** The next three read a shared item by id. Pass a link token, a bearer token, or both. */
+    openShared: async (itemId, opts = {}) => json("GET", `/shared/${id(itemId)}`, { auth: false, headers: link(opts.linkToken), signal: opts.signal }, isItem),
+    listShared: async (itemId, opts = {}) => json("GET", `/shared/${id(itemId)}/items`, { auth: false, headers: link(opts.linkToken), signal: opts.signal }, listOf(isItem)),
+    readShared: async (itemId, opts = {}) => {
+      const { data, contentType } = await bytes(`/shared/${id(itemId)}/content`, { auth: false, headers: link(opts.linkToken), signal: opts.signal });
+      return { data, contentType };
+    }
+  };
+}
+export {
+  DriveApiError,
+  createClient
+};

package/dist/{drive-DKOs1FyM.d.ts → drive-Dlzwukjq.d.ts}

@@ -1,5 +1,5 @@
 import * as agentic_identity from 'agentic-identity';
-import { PrincipalContext, Store, Blobs, createSharing, Role } from 'agentic-identity';
+import { PrincipalContext, Store, Blobs, createSharing, Subject, Role, SubjectKind } from 'agentic-identity';
 
 declare const ROOT_ID = "root";
 declare const ACTOR_KINDS: readonly ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
@@ -87,6 +87,13 @@ declare function parseName(raw: string): {
     name: string;
     key: string;
 };
+/**
+ * The kind that holds a role, for the kind of a principal at the root of a chain. Only the root of a chain holds a
+ * role, so only `human` and `agent` map. Any other kind, a delegated one too, is an error: it never defaults to a person.
+ */
+declare function subjectKindOf(kind: unknown): SubjectKind;
+/** A subject from input: both parts are checked. */
+declare function parseSubject(input: unknown): Subject;
 declare function createDrive(deps: DriveDeps): {
     stat(ctx: Ctx, loc: string): Promise<Node>;
     /** Live children, sorted by name. */
@@ -193,7 +200,7 @@ declare function createDrive(deps: DriveDeps): {
     exportPerson(ctx: Ctx): Promise<{
         subject: {
             id: string;
-            kind: "human" | "agent_of_human" | "agent_of_agent" | "agent" | "user_token" | null;
+            kind: "human" | "agent" | "agent_of_human" | "agent_of_agent" | "user_token" | null;
         };
         partial: boolean;
         authored: {
@@ -220,6 +227,7 @@ declare function createDrive(deps: DriveDeps): {
         }[];
         shares: {
             held: {
+                subjectKind: unknown;
                 subjectId: unknown;
                 resourceId: unknown;
                 role: unknown;
@@ -247,7 +255,7 @@ declare function createDrive(deps: DriveDeps): {
      * 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.
+     * entries of the erased items go with them. The ones about what the person did in other drives stay: they hold ids and kinds only. A failed call can run again.
      */
     erasePerson(ctx: Ctx): Promise<{
         removed: number;
@@ -256,8 +264,8 @@ declare function createDrive(deps: DriveDeps): {
         anonymized: number;
     }>;
     /** Gives a person or an agent a role on an item and everything under it. Only an owner may. */
-    shareWith(ctx: Ctx, loc: string, subjectId: string, role: Role): Promise<void>;
-    unshare(ctx: Ctx, loc: string, subjectId: string): Promise<void>;
+    shareWith(ctx: Ctx, loc: string, subject: Subject, role: Role): Promise<void>;
+    unshare(ctx: Ctx, loc: string, subject: Subject): Promise<void>;
     /** Invite by `email` (a person) or `handle` (an agent). The invite lasts `expiresInMs`, if given. It sends no message. */
     invite(ctx: Ctx, loc: string, input: {
         role: Role;
@@ -285,6 +293,7 @@ declare function createDrive(deps: DriveDeps): {
     /** Who can reach an item, and by which links and invites. Only an owner may look. Link tokens are never shown. */
     shares(ctx: Ctx, loc: string): Promise<{
         grants: {
+            subjectKind: agentic_identity.Json;
             subjectId: agentic_identity.Json;
             role: agentic_identity.Json;
         }[];
@@ -322,4 +331,4 @@ declare function createDrive(deps: DriveDeps): {
     }>;
 };
 
-export { type ActorKind as A, type Ctx as C, type Drive as D, type ErrorCode as E, type Node as N, type OnConflict as O, ROOT_ID as R, type SearchQuery as S, type Actor as a, ACTOR_KINDS as b, type Action as c, type Can as d, type DriveDeps as e, DriveError as f, createDrive as g, parseName as p };
+export { type ActorKind as A, type Ctx as C, type Drive as D, type ErrorCode as E, type Node as N, type OnConflict as O, ROOT_ID as R, type SearchQuery as S, type Actor as a, ACTOR_KINDS as b, type Action as c, type Can as d, type DriveDeps as e, DriveError as f, createDrive as g, parseSubject as h, parseName as p, subjectKindOf as s };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OnConflict, D as Drive, C as Ctx, N as Node, A as ActorKind, a as Actor } from './drive-DKOs1FyM.js';
-export { b as ACTOR_KINDS, c as Action, d as Can, e as DriveDeps, f as DriveError, E as ErrorCode, R as ROOT_ID, S as SearchQuery, g as createDrive, p as parseName } from './drive-DKOs1FyM.js';
+import { O as OnConflict, D as Drive, C as Ctx, N as Node, A as ActorKind, a as Actor } from './drive-Dlzwukjq.js';
+export { b as ACTOR_KINDS, c as Action, d as Can, e as DriveDeps, f as DriveError, E as ErrorCode, R as ROOT_ID, S as SearchQuery, g as createDrive, p as parseName, h as parseSubject, s as subjectKindOf } from './drive-Dlzwukjq.js';
 import { AdapterOptions, Blobs, Store } from 'agentic-identity';
 export { B as BackfillOptions, a as BackfillResult, b as backfillAuthorIds, c as backfillResources } from './migrate-B79gRPMu.js';
 

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-GMA5I5L6.js";
 import {
   backfillAuthorIds,
   backfillResources
-} from "./chunk-3LISWG7H.js";
+} from "./chunk-5KEISBS4.js";
 import {
   ACTOR_KINDS,
   DEFAULT_MAX_BYTES,
@@ -16,12 +16,14 @@ import {
   createFileStore,
   openLocal,
   parseName,
+  parseSubject,
   publicNode,
   readZip,
   sniffMime,
+  subjectKindOf,
   upload,
   writeZip
-} from "./chunk-6CWBHSJ7.js";
+} from "./chunk-VSVIJBMJ.js";
 export {
   ACTOR_KINDS,
   DEFAULT_MAX_BYTES,
@@ -36,9 +38,11 @@ export {
   createFileStore,
   openLocal,
   parseName,
+  parseSubject,
   publicNode,
   readZip,
   sniffMime,
+  subjectKindOf,
   upload,
   writeZip
 };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { D as Drive, C as Ctx } from './drive-DKOs1FyM.js';
+import { D as Drive, C as Ctx } from './drive-Dlzwukjq.js';
 import 'agentic-identity';
 
 declare function createMcpServer(drive: Drive, ctx: Ctx, exportDir: string): McpServer;

package/dist/mcp.js

@@ -1,13 +1,13 @@
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-GMA5I5L6.js";
 import {
   ACTOR_KINDS,
   DriveError,
   buildExport,
   publicNode,
   upload
-} from "./chunk-6CWBHSJ7.js";
+} from "./chunk-VSVIJBMJ.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/worker.d.ts

@@ -1,7 +1,7 @@
 import { Hono } from 'hono';
 import { D1Like, R2Like } from 'agentic-identity/cloudflare';
 import { Store } from 'agentic-identity';
-import { C as Ctx, D as Drive } from './drive-DKOs1FyM.js';
+import { C as Ctx, D as Drive } from './drive-Dlzwukjq.js';
 export { B as BackfillOptions, a as BackfillResult, b as backfillAuthorIds, c as backfillResources } from './migrate-B79gRPMu.js';
 
 interface WorkerEnv {

package/dist/worker.js

@@ -1,7 +1,7 @@
 import {
   backfillAuthorIds,
   backfillResources
-} from "./chunk-3LISWG7H.js";
+} from "./chunk-5KEISBS4.js";
 import {
   DEFAULT_MAX_BYTES,
   DEFAULT_URL_SECONDS,
@@ -11,7 +11,7 @@ import {
   publicNode,
   safeMime,
   upload
-} from "./chunk-6CWBHSJ7.js";
+} from "./chunk-VSVIJBMJ.js";
 
 // src/worker.ts
 import { Hono } from "hono";
@@ -214,11 +214,11 @@ function createApp() {
   api.get("/shares", async (c) => c.json(await c.var.drive.shares(c.var.ctx, need(q(c, "path"), "path"))));
   api.post("/shares", async (c) => {
     const b = await body(c);
-    await c.var.drive.shareWith(c.var.ctx, str(b.path, "path"), str(b.subjectId, "subjectId"), roleOf(b.role));
+    await c.var.drive.shareWith(c.var.ctx, str(b.path, "path"), { kind: b.subjectKind, id: str(b.subjectId, "subjectId") }, roleOf(b.role));
     return c.json({ ok: true });
   });
   api.delete("/shares", async (c) => {
-    await c.var.drive.unshare(c.var.ctx, need(q(c, "path"), "path"), need(q(c, "subjectId"), "subjectId"));
+    await c.var.drive.unshare(c.var.ctx, need(q(c, "path"), "path"), { kind: q(c, "subjectKind"), id: need(q(c, "subjectId"), "subjectId") });
     return c.json({ ok: true });
   });
   api.post("/invites", async (c) => {

package/llms.txt

@@ -5,6 +5,7 @@ Store, sort, and share files and folders.
 Keywords: drive,files,folders,storage,upload,sharing,agents,mcp,cli,r2.
 
 - SDK: import { createDrive } from "agentic-drive".
+- Remote SDK: import { createClient } from "agentic-drive/client". createClient({ baseUrl, token, fetch?, retries? }) has one method for each bearer route and each shared route (list, stat, mkdir, upload, download, move, trash, restore, purge, search, share, createLink, and more). A failed call throws DriveApiError with code and status. It runs in browsers, Workers, and Node 22.
 - CLI: agentic-drive ls /.
 - MCP: run agentic-drive mcp, then call drive_ls.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-drive",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Store, sort, and share files and folders.",
   "keywords": [
     "drive",
@@ -44,6 +44,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./worker": {
       "types": "./dist/worker.d.ts",
       "import": "./dist/worker.js"
@@ -59,7 +63,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "agentic-identity": "^0.3.0",
+    "agentic-identity": "^0.4.0",
     "hono": "^4.13.14",
     "zod": "^3.25.0"
   },