agentic-drive 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-DRACF66Y.js";
 import {
+  AuthError,
   DriveError,
+  NO_TOKEN,
+  addPrincipal,
   buildExport,
+  issueKey,
   openLocal,
   publicNode,
+  resolveToken,
+  revokeKey,
+  revokePrincipal,
   upload
-} from "./chunk-6CWBHSJ7.js";
+} from "./chunk-ATJDMCRV.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

@@ -0,0 +1,173 @@
+import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-Cn3mpuDW.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: 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(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);
+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-Cn3mpuDW.d.ts}

@@ -1,9 +1,9 @@
 import * as agentic_identity from 'agentic-identity';
-import { PrincipalContext, Store, Blobs, createSharing, Role } 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;
@@ -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 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-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 { 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,20 +51,30 @@ 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;
 };
+/** 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. */
 declare function publicNode(node: Node, path?: string): {
     id: string;
@@ -105,4 +115,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 };