agentic-drive 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.5.0
+
+Read the breaking changes before you upgrade or deploy.
+
+### Breaking changes
+
+- **Deploy the Worker and the client together.** Each item in the HTTP, CLI, and MCP output has a `machineMade` field next to `createdBy.kind`. The client now rejects an item with no `machineMade`. A client of 0.5.0 that talks to a Worker of 0.4.0 fails every call that returns items, such as list, stat, and search. Also, `Item` and `PathItem` in the client types now require `machineMade: boolean`. A project that builds those objects itself, such as test fixtures or mocks of the client, must add the field.
+
+### Added
+
+- **Machine-made label from creation on.** The web UI shows "Created by agent" on every item that an agent made, not only after a person edits it.
+
+## 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.

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.5.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
 
@@ -70,7 +102,7 @@ Sharing routes: `GET /shares?path=`, `POST /shares`, `DELETE /shares?path=&subje
 `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.
 
@@ -101,6 +133,63 @@ try {
 - 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>`).

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

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

package/dist/{chunk-VSVIJBMJ.js → chunk-T6C5Y2WA.js}

@@ -1,9 +1,9 @@
 // src/drive.ts
-import { EraseRefusedError, MAX_FOLDER_DEPTH, SUBJECT_KINDS } 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);
@@ -1283,19 +1283,64 @@ 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 { isMachineMade, isScope, issueCredential, revokeCredential } from "agentic-identity";
+function openLocal(dir) {
+  const store = createFileStore(join2(dir, "db"));
+  return { store, drive: createDrive({ store, blobs: createFileBlobs(join2(dir, "blobs")) }) };
+}
+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;
-  return path === void 0 ? rest : { path, ...rest };
+  const shown = { ...rest, machineMade: isMachineMade(node.createdBy.kind) };
+  return path === void 0 ? shown : { path, ...shown };
 }
 
 // src/upload.ts
@@ -1374,7 +1419,15 @@ export {
   buildExport,
   createFileStore,
   createFileBlobs,
+  authenticate,
   openLocal,
+  AuthError,
+  NO_TOKEN,
+  resolveToken,
+  addPrincipal,
+  revokePrincipal,
+  issueKey,
+  revokeKey,
   publicNode,
   DEFAULT_MAX_BYTES,
   sniffMime,

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

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

package/dist/cli.js

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 import {
   VERSION
-} from "./chunk-GMA5I5L6.js";
+} from "./chunk-WQHJNHAR.js";
 import {
+  AuthError,
   DriveError,
+  NO_TOKEN,
+  addPrincipal,
   buildExport,
+  issueKey,
   openLocal,
   publicNode,
+  resolveToken,
+  revokeKey,
+  revokePrincipal,
   upload
-} from "./chunk-VSVIJBMJ.js";
+} from "./chunk-T6C5Y2WA.js";
 
 // src/cli.ts
 import { createReadStream, realpathSync, writeFileSync } from "fs";
@@ -37,23 +44,33 @@ Commands:
   register <ref> <name>        Put an app document in the drive. Flag: --parent <folder>
   forget <ref>                 Move the references to an app document to the trash.
   delete-all --yes             Erase you for good: your drive, and what you shared or held.
+  principal add <id>           Make a person, or an agent with --of <person>. Flag: --scope <s> (repeat). No key needed.
+  principal revoke <id>        Stop a principal, and every agent below it. No key needed.
+  key issue <principal>        Print a new API key for a principal. It shows once. Flag: --label. No key needed.
+  key revoke <key>             Stop a key from working. No key needed.
   mcp                          Start the MCP server on stdio.
 
 Flags:
   --dir <path>        Data folder. Env AGENTIC_DRIVE_DIR. Default ./.agentic-drive
-  --owner <id>        Drive owner. Env AGENTIC_DRIVE_OWNER. Default "me"
-  --actor <id>        Who acts. Env AGENTIC_DRIVE_ACTOR. Default the owner
-  --actor-kind <k>    Actor kind. Env AGENTIC_DRIVE_KIND. Default human
+  --token <key>       Who you are: an API key. Env AGENTIC_DRIVE_TOKEN. Needed by every command
+                      except help, version, principal, and key. Prefer the env var: a flag shows in ps.
+                      The key names a principal, found through agentic-identity. The drive belongs to
+                      the person at the top of that principal's chain. An agent key marks items as
+                      made by a machine. If the key is missing or not valid, the command exits with 3.
   --on-conflict <m>   fail, rename, or replace
   -p, --parents       Create missing parent folders
+
+Exit codes: 0 done, 1 error, 2 bad usage, 3 no principal or an invalid key.
 `;
+var COMMANDS = ["ls", "stat", "mkdir", "upload", "download", "mv", "rm", "trash", "restore", "purge", "search", "export", "home", "register", "forget", "delete-all", "mcp", "principal", "key"];
 var UsageError = class extends Error {
 };
 var options = {
   dir: { type: "string" },
-  owner: { type: "string" },
-  actor: { type: "string" },
-  "actor-kind": { type: "string" },
+  token: { type: "string" },
+  of: { type: "string" },
+  scope: { type: "string", multiple: true },
+  label: { type: "string" },
   "on-conflict": { type: "string" },
   parents: { type: "boolean", short: "p" },
   mime: { type: "string" },
@@ -87,12 +104,21 @@ async function runCli(argv, io) {
     };
     const env = io.env;
     const dir = resolve(values.dir ?? env.AGENTIC_DRIVE_DIR ?? ".agentic-drive");
-    const { drive, ctx } = openLocal({
-      dir,
-      owner: values.owner ?? env.AGENTIC_DRIVE_OWNER ?? "me",
-      actor: values.actor ?? env.AGENTIC_DRIVE_ACTOR,
-      kind: values["actor-kind"] ?? env.AGENTIC_DRIVE_KIND
-    });
+    if (!COMMANDS.includes(command)) throw new UsageError(`unknown command "${command}"`);
+    const admin = command === "principal" || command === "key";
+    const token = values.token ?? env.AGENTIC_DRIVE_TOKEN;
+    if (!admin && !token) throw new AuthError(NO_TOKEN);
+    const { drive, store } = openLocal(dir);
+    if (admin || command === "key") {
+      const [sub, target] = args;
+      const out = (value) => io.out(JSON.stringify(value));
+      if (command === "principal" && sub === "add" && target) return out(await addPrincipal(store, target, { parent: values.of, scopes: values.scope })), 0;
+      if (command === "principal" && sub === "revoke" && target) return await revokePrincipal(store, target), out({ id: target, revoked: true }), 0;
+      if (command === "key" && sub === "issue" && target) return out({ principal: target, token: await issueKey(store, target, values.label) }), 0;
+      if (command === "key" && sub === "revoke" && target) return await revokeKey(store, target), out({ revoked: true }), 0;
+      throw new UsageError("usage: agentic-drive principal add <id> [--of <person>] [--scope <s>] | principal revoke <id> | key issue <principal> | key revoke <key>");
+    }
+    const ctx = await resolveToken(store, token);
     const onConflict = values["on-conflict"];
     if (onConflict && !["fail", "rename", "replace"].includes(onConflict)) throw new UsageError("--on-conflict needs fail, rename, or replace");
     const print = (value) => io.out(JSON.stringify(value));
@@ -199,6 +225,10 @@ async function runCli(argv, io) {
       io.err(JSON.stringify({ error: { code: "USAGE", message: error.message } }));
       return 2;
     }
+    if (error instanceof AuthError) {
+      io.err(JSON.stringify({ error: { code: error.code, message: error.message } }));
+      return 3;
+    }
     if (error instanceof DriveError) {
       io.err(JSON.stringify({ error: { code: error.code, message: error.message } }));
       return 1;

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-Dlzwukjq.js';
+import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-Cn3mpuDW.js';
 import 'agentic-identity';
 
 type Role = "viewer" | "commenter" | "editor" | "owner";
@@ -9,7 +9,10 @@ type Subject = {
     id: string;
 };
 /** An item as the API prints it: no storage keys. */
-type Item = Omit<Node, "nameKey" | "blobKey" | "purging">;
+/** `machineMade` is true when the creator is not a human principal. */
+type Item = Omit<Node, "nameKey" | "blobKey" | "purging"> & {
+    machineMade: boolean;
+};
 /** A search hit, or a home item: an item with its path. */
 type PathItem = Item & {
     path: string;

package/dist/client.js

@@ -43,11 +43,11 @@ 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 ACTOR_KINDS = { human: true, agent_of_human: true, agent_of_agent: true, agent: true, user_token: true };
 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 actor = (v) => record(v) && text(v.id) && oneOf(Object.keys(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) && typeof v.machineMade === "boolean";
 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);

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

@@ -1,9 +1,9 @@
 import * as agentic_identity from 'agentic-identity';
-import { PrincipalContext, Store, Blobs, createSharing, Subject, Role, SubjectKind } from 'agentic-identity';
+import { PrincipalKind, 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"];
-type ActorKind = (typeof ACTOR_KINDS)[number];
+type ActorKind = PrincipalKind;
 type Actor = {
     id: string;
     kind: ActorKind;
@@ -331,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, parseSubject as h, parseName as p, subjectKindOf as s };
+export { type Actor 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, ACTOR_KINDS as a, type Action as b, type ActorKind 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,6 +1,6 @@
-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';
+import { O as OnConflict, D as Drive, C as Ctx, N as Node, A as Actor } from './drive-Cn3mpuDW.js';
+export { a as ACTOR_KINDS, b as Action, c as ActorKind, 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-Cn3mpuDW.js';
+import { AdapterOptions, Blobs, Store, Doc } from 'agentic-identity';
 export { B as BackfillOptions, a as BackfillResult, b as backfillAuthorIds, c as backfillResources } from './migrate-B79gRPMu.js';
 
 declare const VERSION: string;
@@ -51,22 +51,33 @@ declare function writeZip(entries: ZipEntry[], at: number): Uint8Array;
 /** Reads a zip made by `writeZip`. It checks every CRC. */
 declare function readZip(bytes: Uint8Array): Map<string, Uint8Array>;
 
-interface LocalOptions {
-    /** Where the drive keeps its data. */
-    dir: string;
-    /** Whose drive this is. */
-    owner: string;
-    /** Who acts. Defaults to the owner. */
-    actor?: string;
-    /** What kind of actor. Defaults to `human`. Set an agent kind when an agent runs the command. */
-    kind?: ActorKind;
-}
-declare function openLocal(options: LocalOptions): {
+/** The drive and the store behind it, both kept in `dir`. The store holds the principals and keys too. */
+declare function openLocal(dir: string): {
     drive: Drive;
-    ctx: Ctx;
+    store: Store;
 };
-/** A node as the CLI and MCP print it: no storage keys. */
+/** Why no caller could be named. The CLI turns it into exit code 3. */
+declare class AuthError extends Error {
+    readonly code = "UNAUTHENTICATED";
+}
+/**
+ * The caller behind `token`, resolved through agentic-identity like the Worker does. The owner is the root
+ * of the delegation chain, and the actor is the principal itself, so an agent key shows as a machine.
+ */
+declare function resolveToken(store: Store, token: string | undefined): Promise<Ctx>;
+/** Make a principal. One with a parent is an agent of that human. One without is a human. Local data is the trust boundary. */
+declare function addPrincipal(store: Store, id: string, opts: {
+    parent?: string;
+    scopes?: string[];
+}): Promise<Doc>;
+/** Stop a principal. Every agent below it stops too, because its chain is no longer live. */
+declare function revokePrincipal(store: Store, id: string): Promise<void>;
+/** Issue an API key for a principal. The token is shown once. */
+declare function issueKey(store: Store, principalId: string, label?: string): Promise<string>;
+declare function revokeKey(store: Store, token: string): Promise<void>;
+/** A node as the CLI and MCP print it: no storage keys. `machineMade` is true when the creator is not a human principal. */
 declare function publicNode(node: Node, path?: string): {
+    machineMade: boolean;
     id: string;
     owner: string;
     parentId: string;
@@ -85,6 +96,7 @@ declare function publicNode(node: Node, path?: string): {
     trashed: boolean;
     trashedAt: number | null;
 } | {
+    machineMade: boolean;
     id: string;
     owner: string;
     parentId: string;
@@ -105,4 +117,4 @@ declare function publicNode(node: Node, path?: string): {
     path: string;
 };
 
-export { Actor, ActorKind, Ctx, DEFAULT_MAX_BYTES, Drive, Node, OnConflict, type UploadOptions, VERSION, buildExport, createFileBlobs, createFileStore, openLocal, publicNode, readZip, sniffMime, upload, writeZip };
+export { Actor, AuthError, Ctx, DEFAULT_MAX_BYTES, Drive, Node, OnConflict, type UploadOptions, VERSION, addPrincipal, buildExport, createFileBlobs, createFileStore, issueKey, openLocal, publicNode, readZip, resolveToken, revokeKey, revokePrincipal, sniffMime, upload, writeZip };

package/dist/index.js

@@ -1,46 +1,58 @@
 import {
   VERSION
-} from "./chunk-GMA5I5L6.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   backfillAuthorIds,
   backfillResources
-} from "./chunk-5KEISBS4.js";
+} from "./chunk-B7E2Q3RB.js";
 import {
   ACTOR_KINDS,
+  AuthError,
   DEFAULT_MAX_BYTES,
   DriveError,
   ROOT_ID,
+  addPrincipal,
   buildExport,
   createDrive,
   createFileBlobs,
   createFileStore,
+  issueKey,
   openLocal,
   parseName,
   parseSubject,
   publicNode,
   readZip,
+  resolveToken,
+  revokeKey,
+  revokePrincipal,
   sniffMime,
   subjectKindOf,
   upload,
   writeZip
-} from "./chunk-VSVIJBMJ.js";
+} from "./chunk-T6C5Y2WA.js";
 export {
   ACTOR_KINDS,
+  AuthError,
   DEFAULT_MAX_BYTES,
   DriveError,
   ROOT_ID,
   VERSION,
+  addPrincipal,
   backfillAuthorIds,
   backfillResources,
   buildExport,
   createDrive,
   createFileBlobs,
   createFileStore,
+  issueKey,
   openLocal,
   parseName,
   parseSubject,
   publicNode,
   readZip,
+  resolveToken,
+  revokeKey,
+  revokePrincipal,
   sniffMime,
   subjectKindOf,
   upload,

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-Dlzwukjq.js';
+import { D as Drive, C as Ctx } from './drive-Cn3mpuDW.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-GMA5I5L6.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   ACTOR_KINDS,
   DriveError,
   buildExport,
   publicNode,
   upload
-} from "./chunk-VSVIJBMJ.js";
+} from "./chunk-T6C5Y2WA.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";