agentic-drive 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.4.0
+
+Read the breaking changes before you upgrade or deploy.
+
+### Breaking changes
+
+- **The CLI acts as a real principal.** The `--owner`, `--actor`, and `--actor-kind` flags and the `AGENTIC_DRIVE_OWNER`, `_ACTOR`, and `_KIND` variables are gone. Pass an API key with `--token` or `AGENTIC_DRIVE_TOKEN`. agentic-identity resolves the key. With no key, or a revoked or unknown key, the CLI and `mcp` exit with code 3. The default owner `me` is gone.
+- **`openLocal(dir)` takes a folder and returns `{ drive, store }`.** Use `resolveToken(store, token)` to get the `ctx`.
+- **The Worker serves the web UI from `ui-dist`.** `wrangler.jsonc` names `ui-dist` as the assets folder. Run `npm run build:ui` before each `wrangler deploy`. Without the build, the deploy fails because `ui-dist` does not exist. A `ui-dist` left from an older build ships an old UI.
+- **Paths other than `/api/*` and `/health` get the UI.** The assets answer every other path. An unknown GET path returns the UI page with status 200, not a 404 from the Worker. A client that expects a 404 for such a path must change.
+
+### Added
+
+- **`principal add`, `principal revoke`, `key issue`, and `key revoke`** make local principals and keys. `principal add` takes `--of <person>` for an agent and `--scope <s>`, which repeats. `key issue` takes `--label`. The package root also exports `addPrincipal`, `revokePrincipal`, `issueKey`, `revokeKey`, and `AuthError`.
+- **A web UI.** The Worker serves it from `ui-dist` (`npm run build:ui`). It uses agentic-design and the typed client. It has a folder tree, breadcrumbs, a list and a grid, upload by button and by drop, new folder, rename, move, trash and restore, and a share dialog. An item that an agent made shows a "Created by agent" label while a person is its last editor. "Edited by" names the last editor, a person or an agent. A Playwright test with an axe WCAG 2.2 AA check covers each view in light and dark.
+- **A content security policy.** The UI loads scripts and fonts only from its own origin. It allows inline styles. The UI refuses to be framed. It also sends `X-Content-Type-Options: nosniff` and `Referrer-Policy: no-referrer`.
+- **Same-origin downloads.** The UI refuses a download link on another origin. Set `DRIVE_PUBLIC_URL` to the origin that serves the UI.
+- **The UI ships in the package.** `npm pack` runs `build:ui` in `prepack`, and the tarball has `ui-dist`.
+
+### Changed
+
+- `npm run ci:local` and CI also build the UI and run `npm run test:e2e`. The E2E test needs Chromium.
+- The package adds no runtime dependency. The UI build and test tools are dev dependencies.
+- The MCP registry entry names `AGENTIC_DRIVE_TOKEN` as a required secret, and `AGENTIC_DRIVE_DIR` as optional.
+
+### Migration
+
+Local data from 0.3.0 belongs to the owner `me`, or to the id you passed to `--owner`. The data folder does not change. Without the key of that owner, the CLI shows an empty drive. Make the principal and a key, then use the key:
+
+1. Run `npx agentic-drive principal add me`, with your old owner id if it was not `me`. Pass the same `--dir` or `AGENTIC_DRIVE_DIR` as before, if you set one.
+2. Run `export AGENTIC_DRIVE_TOKEN=$(npx agentic-drive key issue me | jq -r .token)`.
+3. Put the same key in each MCP client config as `AGENTIC_DRIVE_TOKEN`, and the same data folder as `AGENTIC_DRIVE_DIR`, if you set one.
+
+## 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

@@ -7,8 +7,22 @@
 
 Store, sort, and share files and folders.
 
-> Status: early. The library, CLI, MCP server, and HTTP API work, with sharing in the SDK and the HTTP API.
-> The web UI is not built yet.
+> Status: 0.4.0, early. The library, CLI, MCP server, and HTTP API work, with sharing in the SDK and the HTTP API.
+> A small web UI works. See [UI](#ui).
+
+## Live demo
+
+A demo Worker runs at https://agentic-drive-demo.hello-fd1.workers.dev. `GET /health` answers 200, and the web UI is served at `/`.
+The API needs a bearer token, so a call without one gets 401. The demo holds throwaway data only, and it can be reset at any time.
+
+To redeploy it, set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` in your shell, then run:
+
+```sh
+npm run deploy:demo
+```
+
+This uses `wrangler.demo.jsonc` (D1 in `weur`, R2 in the EU jurisdiction, `workers_dev` on). The URL signing secret lives in the Worker:
+`openssl rand -hex 32 | npx wrangler secret put DRIVE_URL_SECRET -c wrangler.demo.jsonc`. Deploys are manual. No CI secret is used.
 
 ## Install
 
@@ -42,8 +56,26 @@ npx agentic-drive mcp
 ```
 
 Every command prints JSON. A failure prints `{"error":{"code","message"}}` on stderr and exits 1.
-Set `--dir`, `--owner`, `--actor`, and `--actor-kind` (or the `AGENTIC_DRIVE_*` variables).
-An agent sets `--actor-kind agent_of_human`. Each item then records that a machine made it.
+Exit code 2 means bad usage. Exit code 3 means no principal, or a key that is not valid.
+
+Every command except `help`, `version`, `principal`, and `key` needs a principal. Pass an API key with
+`--token <key>` or `AGENTIC_DRIVE_TOKEN`. Prefer the variable: a flag shows in `ps`.
+`agentic-identity` resolves the key. The drive belongs to the person at the top of the
+principal's chain. An agent key marks each item it makes as made by a machine. A revoked,
+expired, or unknown key fails with exit code 3.
+
+```sh
+npx agentic-drive principal add alice
+export AGENTIC_DRIVE_TOKEN=$(npx agentic-drive key issue alice | jq -r .token)
+npx agentic-drive principal add helper --of alice     # an agent of alice
+npx agentic-drive key issue helper                    # the key shows once
+npx agentic-drive key revoke <key>
+npx agentic-drive principal revoke helper             # stops its keys, and its agents
+```
+
+`principal` and `key` need no key: anyone who can read the `--dir` folder can run them.
+Set `--dir` (or `AGENTIC_DRIVE_DIR`) to choose the data folder.
+The local drive checks the owner only. It does not apply the scopes of an agent key.
 
 ## HTTP API
 
@@ -66,14 +98,98 @@ 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`.
-Without `DRIVE_URL_SECRET` or `DRIVE_PUBLIC_URL`, every request gets 503.
+Without `DRIVE_URL_SECRET` or `DRIVE_PUBLIC_URL`, every API request gets 503. `/health` still answers.
 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")`.
+
+## UI
+
+The Worker serves a small web UI. It uses the [agentic-design](https://www.npmjs.com/package/agentic-design) package and the typed client of this package (`agentic-drive/client`). It has a folder tree, breadcrumbs, a file list and grid, upload by button or by drag and drop, new folder, rename, move, trash and restore, and a share dialog with roles and a link. An item that an agent made shows a "Created by agent" label while a person is its last editor. "Edited by" names the last editor, a person or an agent. It works with the keyboard. An automated axe check for WCAG 2.2 AA passes on each view in the light and dark themes.
+
+Run it locally:
+
+```sh
+npm ci
+npm run build:ui
+WRANGLER_SEND_METRICS=false npx wrangler dev --local \
+  --var DRIVE_PUBLIC_URL:http://127.0.0.1:8787 \
+  --var DRIVE_URL_SECRET:<32 or more characters> --var DRIVE_REGION:unknown
+```
+
+Open `http://127.0.0.1:8787` and sign in with a bearer token. The tab keeps the token until you close it. A fresh local database has no tokens. `e2e/serve.mjs` shows how to seed a person and an agent.
+
+Test it with `npm run test:e2e`. The test starts `wrangler dev` on a seeded database, drives the UI in Chromium, and runs an axe WCAG 2.2 AA check on each view in both themes. Run `npx playwright install chromium` once first. The run also writes the screenshots in [docs/ui](docs/ui).
+
+Run `npm run build:ui` before `npm run test:e2e` or `wrangler deploy`, because the Worker config names the `ui-dist` folder. The UI answers with a content security policy that loads scripts and fonts only from its own origin, and it refuses to be framed.
+
+Set `DRIVE_PUBLIC_URL` to the origin that serves the UI. A download link on another origin is refused.
+
+### Serve the UI from the package
+
+The npm package ships the built UI in `ui-dist`. The package does not ship a `wrangler.jsonc`, so a project that deploys its own Worker adds the assets block to its config. Its Worker re-exports the package Worker. In a workspace, the package can sit in the root `node_modules`. Then point `assets.directory` at that folder, such as `../../node_modules/agentic-drive/ui-dist`:
+
+```js
+// src/worker.js
+export { default } from "agentic-drive/worker";
+```
+
+```jsonc
+// wrangler.jsonc: the Worker reads the bindings DB (D1) and FILES (R2). Name yours the same.
+// Create the bucket with `wrangler r2 bucket create agentic-drive-files --jurisdiction eu`.
+// Create the database with `wrangler d1 create agentic-drive --location weur`, then put its id below.
+{
+  "name": "agentic-drive",
+  "main": "src/worker.js",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "d1_databases": [{ "binding": "DB", "database_name": "agentic-drive", "database_id": "<your id>" }],
+  "r2_buckets": [{ "binding": "FILES", "bucket_name": "agentic-drive-files", "jurisdiction": "eu" }],
+  // In a workspace, point this at the root node_modules instead.
+  "assets": { "directory": "./node_modules/agentic-drive/ui-dist", "not_found_handling": "single-page-application", "run_worker_first": ["/api/*", "/health"] }
+}
+```
+
+Set `DRIVE_URL_SECRET` and `DRIVE_PUBLIC_URL` with `npx wrangler secret put`. `DRIVE_URL_SECRET` needs 32 bytes or more. `DRIVE_PUBLIC_URL` is the origin of this Worker. The Worker declares region `eu` unless `DRIVE_REGION` says otherwise, so keep the EU jurisdiction and location above. Sign-in uses agentic-identity credentials in the same D1 database. Create a token there first, or every bearer API request gets 401. In the D1 database:
+
+1. Create the table, unless a request has already run: `wrangler d1 execute agentic-drive --remote --command "CREATE TABLE IF NOT EXISTS store_docs (collection TEXT NOT NULL, id TEXT NOT NULL, body TEXT NOT NULL, version INTEGER NOT NULL DEFAULT 1, PRIMARY KEY (collection, id)) WITHOUT ROWID"`.
+2. Insert a row into `store_docs` with `collection` `principals` and `id` `me`. Its body is `{ "id": "me", "kind": "human", "scopes": ["drive:admin"] }`.
+3. Make the token with `openssl rand -hex 32`. A token may use only letters, digits, `_`, and `-`, up to 512 characters. Insert a row into `store_docs` with `collection` `credentials`. Its `id` is the lowercase hex SHA-256 of the token, which `printf %s "$TOKEN" | sha256sum` prints. Its body is `{ "principalId": "me", "kind": "api_key" }`.
+
+The [seed script](https://github.com/pooriaarab/agentic-drive/blob/main/e2e/serve.mjs) shows these rows. Its tokens are for tests only. Never use them in a deployment. Without both secrets, the API answers 503. With this config, `/` serves the UI, and `/health` and `/api/v1/drive/*` answer from the Worker.
+
+The UI does not make snapshot links yet. The address of a share link shows once, when you create it.
+
 ## Features
 
 - Folders, files, and typed references to documents in other apps (`docs:<id>`).
@@ -83,14 +199,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-6CWBHSJ7.js → chunk-ATJDMCRV.js}

@@ -1,9 +1,9 @@
 // src/drive.ts
-import { MAX_FOLDER_DEPTH } from "agentic-identity";
+import { EraseRefusedError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, SUBJECT_KINDS } from "agentic-identity";
 var ROOT_ID = "root";
 var NODES = "drive_nodes";
 var NAMES = "drive_names";
-var ACTOR_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+var ACTOR_KINDS = PRINCIPAL_KINDS;
 var DriveError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -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 }))
       };
@@ -1254,15 +1283,59 @@ function createFileBlobs(dir, options = {}) {
   };
 }
 
+// src/auth.ts
+import { createStoreAuth } from "agentic-identity";
+async function authenticate(request, store, now) {
+  if (!/^Bearer [A-Za-z0-9_-]{1,512}$/.test(request.headers.get("authorization") ?? "")) return null;
+  const principal = await createStoreAuth(store, now ? { now } : {}).authenticate(request);
+  return principal ? { owner: principal.chain[0].id, actor: { id: principal.principalId, kind: principal.kind }, principal } : null;
+}
+
 // src/local.ts
+import { createHash as createHash2 } from "crypto";
 import { join as join2 } from "path";
-function openLocal(options) {
-  const kind = options.kind ?? "human";
-  if (!ACTOR_KINDS.includes(kind)) throw new Error(`unknown actor kind "${kind}"`);
-  return {
-    drive: createDrive({ store: createFileStore(join2(options.dir, "db")), blobs: createFileBlobs(join2(options.dir, "blobs")) }),
-    ctx: { owner: options.owner, actor: { id: options.actor ?? options.owner, kind } }
-  };
+import { isScope, issueCredential, revokeCredential } from "agentic-identity";
+function openLocal(dir) {
+  const store = createFileStore(join2(dir, "db"));
+  return { store, drive: createDrive({ store, blobs: createFileBlobs(join2(dir, "blobs")) }) };
+}
+var AuthError = class extends Error {
+  code = "UNAUTHENTICATED";
+};
+var NO_TOKEN = "no principal: pass --token <key> or set AGENTIC_DRIVE_TOKEN to an API key";
+var BAD_TOKEN = "the key is not valid: it is unknown, revoked, or expired, or its principal is revoked";
+async function resolveToken(store, token) {
+  if (!token) throw new AuthError(NO_TOKEN);
+  if (!/^[A-Za-z0-9_-]{1,512}$/.test(token)) throw new AuthError(BAD_TOKEN);
+  const ctx = await authenticate(new Request("http://local", { headers: { authorization: `Bearer ${token}` } }), store);
+  if (!ctx) throw new AuthError(BAD_TOKEN);
+  return ctx;
+}
+async function addPrincipal(store, id, opts) {
+  if (!/^[A-Za-z0-9_.@-]{1,128}$/.test(id)) throw new Error(`invalid principal id "${id}"`);
+  const scopes = opts.scopes?.length ? opts.scopes : [opts.parent ? "drive:write" : "drive:admin"];
+  const bad = scopes.find((s) => !isScope(s));
+  if (bad !== void 0) throw new Error(`invalid scope "${bad}"`);
+  if (await store.get("principals", id)) throw new Error(`principal "${id}" exists`);
+  if (opts.parent && !await store.get("principals", opts.parent)) throw new Error(`parent "${opts.parent}" does not exist`);
+  const parent = opts.parent ? await store.get("principals", opts.parent) : null;
+  if (parent && parent.kind !== "human") throw new Error(`parent "${opts.parent}" is not a person`);
+  const doc = opts.parent ? { id, kind: "agent_of_human", parentId: opts.parent, scopes } : { id, kind: "human", scopes };
+  await store.put("principals", id, doc);
+  return doc;
+}
+async function revokePrincipal(store, id) {
+  const doc = await store.get("principals", id);
+  if (!doc) throw new DriveError("NOT_FOUND", `principal "${id}" does not exist`);
+  await store.put("principals", id, { ...doc, revokedAt: Date.now() });
+}
+async function issueKey(store, principalId, label) {
+  if (!await store.get("principals", principalId)) throw new Error(`principal "${principalId}" does not exist`);
+  return issueCredential(store, { principalId, kind: "api_key", ...label ? { label } : {} });
+}
+async function revokeKey(store, token) {
+  if (!await store.get("credentials", createHash2("sha256").update(token).digest("hex"))) throw new DriveError("NOT_FOUND", "no such key");
+  await revokeCredential(store, token, Date.now());
 }
 function publicNode(node, path) {
   const { nameKey: _nameKey, blobKey: _blobKey, purging: _purging, ...rest } = node;
@@ -1337,13 +1410,23 @@ export {
   safeMime,
   parseName,
   rootResource,
+  subjectKindOf,
+  parseSubject,
   createDrive,
   writeZip,
   readZip,
   buildExport,
   createFileStore,
   createFileBlobs,
+  authenticate,
   openLocal,
+  AuthError,
+  NO_TOKEN,
+  resolveToken,
+  addPrincipal,
+  revokePrincipal,
+  issueKey,
+  revokeKey,
   publicNode,
   DEFAULT_MAX_BYTES,
   sniffMime,

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

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

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

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