agentic-comments 0.4.0 → 0.5.1

package/README.md

@@ -18,8 +18,6 @@ copy of `yjs`, because the package checks the Yjs types of your document. Instal
 npm install agentic-comments yjs
 ```
 
-To build from source, see Develop.
-
 ## Quick start
 
 ```ts
@@ -165,10 +163,6 @@ machine. It cannot check a lock held in another container or on another machine.
 share a volume can have the same process id, and each then clears the other's lock, so they can lose writes. A save that
 would pass 50 MB is refused.
 
-If the version you install has no `agentic-comments` command, build from source (see [Develop](#develop)).
-In the cloned repo, run `npm run build` and use `node dist/cli.js` where these examples say
-`npx agentic-comments`.
-
 ```sh
 export AGENTIC_COMMENTS_FILE=./comments.ydoc
 export AGENTIC_COMMENTS_AS=human:ada          # kind:name. The operator sets this.
@@ -180,10 +174,10 @@ npx agentic-comments accept <id>
 ```
 
 - Commands: `init`, `list`, `show`, `comment`, `reply`, `resolve`, `reopen`, `relocate`, `suggestions`,
-  `suggest`, `accept`, `reject`, `mcp`. Run `agentic-comments --help` for flags.
+  `suggest`, `accept`, `reject`, `mcp`. Run `npx agentic-comments --help` for flags.
 - Every result is JSON. An error is JSON on stderr with a `code`, and the exit code is 1. A usage error
   exits 2.
-- The principal comes from `--as` or `AGENTIC_COMMENTS_AS`. Scopes come only from
+- The principal comes from `--as` or `AGENTIC_COMMENTS_AS`, as `kind:name`. The name starts with A-Z a-z 0-9 `_` `-`, then uses A-Z a-z 0-9 `.` `_` `-`, and is at most 128 characters. Scopes come only from
   `AGENTIC_COMMENTS_SCOPES`, a comma list such as `comments:accept`. No flag takes a scope or an author,
   and a flag that does not apply to a command is refused. `AGENTIC_COMMENTS_LOCK_TIMEOUT_MS` sets the wait
   for a lock, in whole milliseconds.
@@ -203,9 +197,13 @@ npx agentic-comments accept <id>
 document in a D1 database through the `Store` port of `agentic-identity`. It checks every request with the
 `Auth` port, so the host picks who the caller is and no request carries an author.
 
-Set the principals as a secret. It is JSON from a bearer token (32 bytes or more) to `kind:name`, or to
-`{ "as": "kind:name", "scopes": [...] }`. One bad entry refuses the whole table. A request with no valid
-token gets `401`.
+Set the principals as a secret. It is JSON from a bearer token to `kind:name`, or to
+`{ "as": "kind:name", "scopes": [...] }`. A token is 32 to 512 bytes, from A-Z a-z 0-9 `_` `-`, so a base64 token with `+` or `/` is refused.
+A name starts with A-Z a-z 0-9 `_` `-`, then uses A-Z a-z 0-9 `.` `_` `-`, and is at most 128 characters.
+One bad entry refuses the whole table. A request with no valid token gets `401`.
+A request whose `Authorization` header is not `Bearer` followed by 1 to 512 bytes of A-Z a-z 0-9 `_` `-` gets `401`, before any custom `Auth` runs.
+A write with no `Authorization` header (a session cookie, for example) gets `403` unless its `Origin` is in the `origins`
+option of `createApp`. The default lists none.
 
 ```sh
 wrangler secret put AGENTIC_COMMENTS_TOKENS
@@ -243,6 +241,34 @@ curl -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
   http://127.0.0.1:8787/api/v1/docs/d1/threads
 ```
 
+## HTTP client
+
+`agentic-comments/client` is a typed client for the Worker routes. It uses only `fetch`, so it runs in browsers,
+Workers, and Node.
+
+```ts
+import { createClient, CommentsApiError } from "agentic-comments/client";
+
+const comments = createClient({ baseUrl: "https://comments.example.com", token });
+await comments.createDocument({ id: "d1", text: "The quick brown fox" });
+const thread = await comments.addThread("d1", { anchor: { type: "text", quote: "fox" }, body: "Which fox?" });
+await comments.reply("d1", thread.id, { body: "This one." });
+try {
+  await comments.accept("d1", "missing");
+} catch (error) {
+  if (error instanceof CommentsApiError) console.error(error.code, error.status);
+}
+```
+
+- The methods match the routes: `me`, `createDocument`, `getDocument`, `listThreads`, `getThread`, `addThread`, `reply`,
+  `resolve`, `reopen`, `relocate`, `listSuggestions`, `suggest`, `accept`, `reject`. Each takes an optional `{ signal }`.
+- `baseUrl` is the Worker URL, `http` or `https`, with no query, hash, or credentials.
+- The client never sends an author. The Worker stamps one from the token.
+- A failed call throws `CommentsApiError`. `code` is the API error code, or `UNKNOWN` when the reply is not an API
+  error. `status` is the HTTP status. A `200` reply with the wrong shape also fails as `UNKNOWN`.
+- The client never follows a redirect and never retries. A write that you abort after the client sends it can still apply:
+  read the thread before you try again.
+
 ## Live demo
 
 A demo Worker runs at <https://agentic-comments-demo.hello-fd1.workers.dev>. It is a staging site. Check it with

package/dist/{chunk-HXXJNFEO.js → chunk-QJXI3P5D.js}

@@ -244,6 +244,7 @@ var FileStore = class {
 };
 
 // src/operator.ts
+import { PrincipalParseError, parsePrincipal } from "agentic-identity";
 function operatorActor(as, scopes) {
   const value = as?.trim();
   const cut = value === void 0 ? -1 : value.indexOf(":");
@@ -251,7 +252,13 @@ function operatorActor(as, scopes) {
     throw new CommentsError("INVALID_AUTHOR", `set the principal as kind:name, for example human:ada. Kinds: ${PRINCIPAL_KINDS.join(", ")}`);
   }
   const list = scopes === void 0 || scopes.trim() === "" ? [] : scopes.split(",").map((s) => s.trim());
-  return stamp({ kind: value.slice(0, cut), name: value.slice(cut + 1), scopes: list });
+  try {
+    const { kind, id } = parsePrincipal({ kind: value.slice(0, cut), id: value.slice(cut + 1) });
+    return stamp({ kind, name: id, scopes: list });
+  } catch (error) {
+    if (!(error instanceof PrincipalParseError)) throw error;
+    throw new CommentsError("INVALID_AUTHOR", `the principal needs a known kind (${PRINCIPAL_KINDS.join(", ")}) and a name of A-Z a-z 0-9 . _ -`);
+  }
 }
 
 export {

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

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

package/dist/{chunk-R4LH36VG.js → chunk-TFRLOBJW.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-REFQNIEP.js";
 import {
   CommentsService
 } from "./chunk-NQWRFKJ6.js";

package/dist/cli.js

@@ -3,10 +3,10 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-HXXJNFEO.js";
+} from "./chunk-QJXI3P5D.js";
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-REFQNIEP.js";
 import {
   CommentsService,
   TEXT_ROOT
@@ -155,7 +155,7 @@ async function runCli(argv, io) {
       return 0;
     }
     if (p.command === "mcp") {
-      const { startMcp } = await import("./mcp-ACC4QIEM.js");
+      const { startMcp } = await import("./mcp-XUV3RPOO.js");
       await startMcp(store, operatorActor(p.flags["--as"] ?? io.env.AGENTIC_COMMENTS_AS, io.env.AGENTIC_COMMENTS_SCOPES));
       return 0;
     }

package/dist/client.d.ts

@@ -0,0 +1,72 @@
+import { L as ListFilter, A as AnchorSpec } from './service-hpWbnSmc.js';
+import { C as CommentsErrorCode } from './errors-CNgWMVQT.js';
+import { PrincipalKind } from 'agentic-identity';
+export { PrincipalKind } from 'agentic-identity';
+import { T as Thread, N as NewReply, M as Message, S as Suggestion } from './suggestions-CvJwo6r4.js';
+import 'yjs';
+
+/** Codes the comment rules return, plus the ones the Worker and its auth return. */
+type ApiErrorCode = CommentsErrorCode | "UNAUTHENTICATED" | "NOT_FOUND" | "INTERNAL" | "UNKNOWN";
+/** Thrown for every reply that is not a success. `code` is the API error code and `status` is the HTTP status. */
+declare class CommentsApiError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    constructor(code: ApiErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** The Worker origin, for example https://comments.example.com. The client adds /api/v1. */
+    baseUrl: string;
+    /** A bearer credential that the Worker's auth accepts. */
+    token: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Every method takes an optional signal. An aborted call rejects with the signal reason, not a
+ * CommentsApiError. A write that was aborted after it was sent may still have applied: read the
+ * thread before you try again.
+ */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+interface Me {
+    kind: PrincipalKind;
+    name: string;
+    scopes: string[];
+}
+type ThreadFilter = ListFilter;
+type SuggestionListFilter = Pick<ListFilter, "status" | "anchorState">;
+interface CommentsClient {
+    me(options?: CallOptions): Promise<Me>;
+    createDocument(input: {
+        id: string;
+        text?: string;
+    }, options?: CallOptions): Promise<{
+        id: string;
+    }>;
+    getDocument(docId: string, options?: CallOptions): Promise<{
+        id: string;
+        text: string;
+    }>;
+    listThreads(docId: string, filter?: ThreadFilter, options?: CallOptions): Promise<Thread[]>;
+    getThread(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    addThread(docId: string, input: {
+        anchor: AnchorSpec;
+        body: string;
+        mentions?: string[];
+    }, options?: CallOptions): Promise<Thread>;
+    reply(docId: string, threadId: string, input: NewReply, options?: CallOptions): Promise<Message>;
+    resolve(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    reopen(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    relocate(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    listSuggestions(docId: string, filter?: SuggestionListFilter, options?: CallOptions): Promise<Suggestion[]>;
+    suggest(docId: string, input: {
+        anchor: AnchorSpec;
+        change: unknown;
+        summary?: string;
+    }, options?: CallOptions): Promise<Suggestion>;
+    accept(docId: string, suggestionId: string, options?: CallOptions): Promise<Suggestion>;
+    reject(docId: string, suggestionId: string, options?: CallOptions): Promise<Suggestion>;
+}
+declare function createClient(options: ClientOptions): CommentsClient;
+
+export { AnchorSpec, type ApiErrorCode, type CallOptions, type ClientOptions, CommentsApiError, type CommentsClient, CommentsErrorCode, ListFilter, type Me, Message, NewReply, Suggestion, type SuggestionListFilter, Thread, type ThreadFilter, createClient };

package/dist/client.js

@@ -0,0 +1,135 @@
+// src/client.ts
+var CODES = {
+  INVALID_AUTHOR: true,
+  INVALID_INPUT: true,
+  INVALID_ANCHOR: true,
+  NO_THREAD: true,
+  THREAD_RESOLVED: true,
+  CORRUPT: true,
+  NO_SUGGESTION: true,
+  FORBIDDEN: true,
+  ALREADY_DECIDED: true,
+  APPLY_FAILED: true,
+  RELOCATE_FAILED: true,
+  STORE_MISSING: true,
+  STORE_EXISTS: true,
+  STORE_CORRUPT: true,
+  STORE_LOCKED: true,
+  STORE_FULL: true,
+  NO_DOCUMENT: true,
+  DOCUMENT_EXISTS: true,
+  CONFLICT: true,
+  MISCONFIGURED: true,
+  USAGE: true,
+  UNAUTHENTICATED: true,
+  NOT_FOUND: true,
+  INTERNAL: true,
+  UNKNOWN: true
+};
+var isKnownCode = (v) => typeof v === "string" && Object.hasOwn(CODES, v);
+var CommentsApiError = class extends Error {
+  code;
+  status;
+  constructor(code, status, message) {
+    super(message);
+    this.name = "CommentsApiError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var KINDS = { human: true, agent_of_human: true, agent_of_agent: true, agent: true, user_token: true };
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isString = (v) => typeof v === "string";
+var SHAPES = {
+  me: (v) => isObject(v) && (typeof v.kind === "string" && Object.hasOwn(KINDS, v.kind)) && isString(v.name) && Array.isArray(v.scopes),
+  created: (v) => isObject(v) && isString(v.id),
+  document: (v) => isObject(v) && isString(v.id) && isString(v.text),
+  thread: (v) => isObject(v) && isString(v.id) && isObject(v.anchor) && (v.status === "open" || v.status === "resolved") && Array.isArray(v.messages),
+  threads: (v) => Array.isArray(v) && v.every(SHAPES.thread),
+  message: (v) => isObject(v) && isString(v.id) && isString(v.body) && isObject(v.author),
+  suggestion: (v) => isObject(v) && isString(v.id) && isObject(v.anchor) && isString(v.status) && isObject(v.author),
+  suggestions: (v) => Array.isArray(v) && v.every(SHAPES.suggestion)
+};
+function createClient(options) {
+  if (typeof options.baseUrl !== "string" || options.baseUrl === "") throw new TypeError("createClient needs a baseUrl");
+  if (typeof options.token !== "string" || options.token === "") throw new TypeError("createClient needs a token");
+  let origin;
+  try {
+    origin = new URL(options.baseUrl);
+  } catch {
+    throw new TypeError("baseUrl must be an absolute URL");
+  }
+  if (origin.protocol !== "https:" && origin.protocol !== "http:") throw new TypeError("baseUrl must be an http or https URL");
+  if (origin.search !== "" || origin.hash !== "" || origin.username !== "" || origin.password !== "") {
+    throw new TypeError("baseUrl must have no query, hash, or credentials");
+  }
+  const root = `${origin.origin}${origin.pathname.replace(/\/+$/, "")}/api/v1`;
+  const token = options.token;
+  const send = (input, init) => {
+    const run = options.fetch ?? globalThis.fetch;
+    return run(input, init);
+  };
+  const seg = (value) => {
+    if (typeof value !== "string" || /^(?:\.|%2e){0,2}$/i.test(value)) throw new TypeError("an id must be a non-empty string that is not . or ..");
+    return encodeURIComponent(value);
+  };
+  const query = (filter) => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filter ?? {})) if (value !== void 0) params.set(key, String(value));
+    const text = params.toString();
+    return text === "" ? "" : `?${text}`;
+  };
+  async function call(method, path, body, callOptions, shape) {
+    const headers = { authorization: `Bearer ${token}` };
+    if (body !== void 0) headers["content-type"] = "application/json";
+    const response = await send(`${root}${path}`, {
+      method,
+      headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      signal: callOptions?.signal,
+      // Never follow a redirect: it would send a write to another host.
+      redirect: "manual"
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text === "" ? void 0 : JSON.parse(text);
+    } catch {
+      parsed = void 0;
+    }
+    if (!response.ok) {
+      const error = parsed?.error;
+      const code = isKnownCode(error?.code) ? error.code : "UNKNOWN";
+      const message = typeof error?.message === "string" ? error.message : `HTTP ${response.status}`;
+      throw new CommentsApiError(code, response.status, message);
+    }
+    if (!SHAPES[shape](parsed)) throw new CommentsApiError("UNKNOWN", response.status, `the reply is not a ${shape}`);
+    return parsed;
+  }
+  const doc = (id) => `/docs/${seg(id)}`;
+  const thread = (id, threadId) => `${doc(id)}/threads/${seg(threadId)}`;
+  const suggestion = (id, suggestionId) => `${doc(id)}/suggestions/${seg(suggestionId)}`;
+  const methods = {
+    me: (o) => call("GET", "/me", void 0, o, "me"),
+    createDocument: (input, o) => call("POST", "/docs", input, o, "created"),
+    getDocument: (id, o) => call("GET", doc(id), void 0, o, "document"),
+    listThreads: (id, filter, o) => call("GET", `${doc(id)}/threads${query(filter)}`, void 0, o, "threads"),
+    getThread: (id, threadId, o) => call("GET", thread(id, threadId), void 0, o, "thread"),
+    addThread: (id, input, o) => call("POST", `${doc(id)}/threads`, input, o, "thread"),
+    reply: (id, threadId, input, o) => call("POST", `${thread(id, threadId)}/replies`, input, o, "message"),
+    resolve: (id, threadId, o) => call("POST", `${thread(id, threadId)}/resolve`, void 0, o, "thread"),
+    reopen: (id, threadId, o) => call("POST", `${thread(id, threadId)}/reopen`, void 0, o, "thread"),
+    relocate: (id, threadId, o) => call("POST", `${thread(id, threadId)}/relocate`, void 0, o, "thread"),
+    listSuggestions: (id, filter, o) => call("GET", `${doc(id)}/suggestions${query(filter)}`, void 0, o, "suggestions"),
+    suggest: (id, input, o) => call("POST", `${doc(id)}/suggestions`, input, o, "suggestion"),
+    accept: (id, suggestionId, o) => call("POST", `${suggestion(id, suggestionId)}/accept`, void 0, o, "suggestion"),
+    reject: (id, suggestionId, o) => call("POST", `${suggestion(id, suggestionId)}/reject`, void 0, o, "suggestion")
+  };
+  return Object.fromEntries(
+    Object.entries(methods).map(([name, method]) => [name, async (...args) => method(...args)])
+  );
+}
+export {
+  CommentsApiError,
+  createClient
+};

package/dist/errors-CNgWMVQT.d.ts

@@ -0,0 +1,7 @@
+type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
+declare class CommentsError extends Error {
+    readonly code: CommentsErrorCode;
+    constructor(code: CommentsErrorCode, message: string);
+}
+
+export { type CommentsErrorCode as C, CommentsError as a };

package/dist/index.d.ts

@@ -1,16 +1,11 @@
-import { a as Author, C as Comments, b as Suggestions } from './suggestions-oj8fd-nG.js';
-export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, S as Suggestion, p as SuggestionFilter, q as SuggestionHost, r as TextAnchor, T as Thread, s as ThreadFilter, t as authorLabel, u as stamp, v as textAnchor, w as textOf } from './suggestions-oj8fd-nG.js';
+import { a as Author, C as Comments, b as Suggestions } from './suggestions-CvJwo6r4.js';
+export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, S as Suggestion, p as SuggestionFilter, q as SuggestionHost, r as TextAnchor, T as Thread, s as ThreadFilter, t as authorLabel, u as stamp, v as textAnchor, w as textOf } from './suggestions-CvJwo6r4.js';
+export { a as CommentsError, C as CommentsErrorCode } from './errors-CNgWMVQT.js';
 export { PRINCIPAL_KINDS, PrincipalKind } from 'agentic-identity';
 import 'yjs';
 
 declare const VERSION: string;
 
-type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
-declare class CommentsError extends Error {
-    readonly code: CommentsErrorCode;
-    constructor(code: CommentsErrorCode, message: string);
-}
-
 type CommentEventType = "thread.created" | "message.added" | "mention" | "thread.resolved" | "thread.reopened" | "suggestion.created" | "suggestion.accepted" | "suggestion.rejected";
 /**
  * One change, in terms a notifier can route. It holds ids and never the text of a comment, a suggestion, or
@@ -103,4 +98,4 @@ declare class Notifications {
     private decided;
 }
 
-export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, CommentsError, type CommentsErrorCode, Notifications, type NotificationsOptions, Suggestions, VERSION };
+export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, Notifications, type NotificationsOptions, Suggestions, VERSION };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-REFQNIEP.js";
 import {
   ACCEPT_SCOPE,
   Actor,

package/dist/local.d.ts

@@ -1,6 +1,6 @@
 import * as Y from 'yjs';
-export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-Dxw9TVxY.js';
-import { q as SuggestionHost, A as Actor } from './suggestions-oj8fd-nG.js';
+export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-hpWbnSmc.js';
+import { q as SuggestionHost, A as Actor } from './suggestions-CvJwo6r4.js';
 import 'agentic-identity';
 
 /** The most bytes a saved document holds. A save over this is refused, so a file never grows past what a load accepts. */

package/dist/local.js

@@ -3,7 +3,7 @@ import {
   MAX_FILE,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-HXXJNFEO.js";
+} from "./chunk-QJXI3P5D.js";
 import {
   CommentsService,
   TEXT_ROOT,

package/dist/{mcp-ACC4QIEM.js → mcp-XUV3RPOO.js}

@@ -1,8 +1,8 @@
 import {
   createMcpServer,
   startMcp
-} from "./chunk-R4LH36VG.js";
-import "./chunk-DRACF66Y.js";
+} from "./chunk-TFRLOBJW.js";
+import "./chunk-REFQNIEP.js";
 import "./chunk-NQWRFKJ6.js";
 import "./chunk-BSNBDKR2.js";
 export {

package/dist/mcp-bin.js

@@ -3,13 +3,13 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-HXXJNFEO.js";
+} from "./chunk-QJXI3P5D.js";
 import {
   startMcp
-} from "./chunk-R4LH36VG.js";
+} from "./chunk-TFRLOBJW.js";
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-REFQNIEP.js";
 import "./chunk-NQWRFKJ6.js";
 import "./chunk-BSNBDKR2.js";
 

package/dist/{service-Dxw9TVxY.d.ts → service-hpWbnSmc.d.ts}

@@ -1,5 +1,5 @@
 import * as Y from 'yjs';
-import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-oj8fd-nG.js';
+import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-CvJwo6r4.js';
 
 /** Where a comment or suggestion points, in terms a person or agent can write down. */
 type AnchorSpec = {

package/dist/worker.d.ts

@@ -1,8 +1,9 @@
 import { Hono } from 'hono';
 import { Auth, Store, PrincipalContext, Region } from 'agentic-identity';
+import { RequirePrincipalOptions } from 'agentic-identity/http';
 import { D1Like } from 'agentic-identity/cloudflare';
-import { A as Actor } from './suggestions-oj8fd-nG.js';
-import { C as CommentsService } from './service-Dxw9TVxY.js';
+import { A as Actor } from './suggestions-CvJwo6r4.js';
+import { C as CommentsService } from './service-hpWbnSmc.js';
 import 'yjs';
 
 interface WorkerEnv {
@@ -13,7 +14,7 @@ interface WorkerEnv {
     /** D1 database: each document, with its threads, as a Yjs update. */
     DB?: D1Like;
     /**
-     * JSON object: bearer token (32 bytes or more) to `kind:name`, or to `{ "as": "kind:name", "scopes": ["comments:write"] }`.
+     * JSON object: bearer token (32 to 512 bytes of A-Z a-z 0-9 _ -) to `kind:name` (the name uses A-Z a-z 0-9 . _ -), or to `{ "as": "kind:name", "scopes": ["comments:write"] }`.
      * Set it as a secret. A short token or a bad entry refuses the whole config.
      */
     AGENTIC_COMMENTS_TOKENS?: string;
@@ -39,6 +40,8 @@ type DocsSource = CommentsDocs | ((env: WorkerEnv) => Promise<CommentsDocs>);
 interface AppOptions {
     /** The credential check. The default reads `AGENTIC_COMMENTS_TOKENS`. Pass any `Auth` from agentic-identity to replace it. */
     auth?: Auth | ((env: WorkerEnv) => Auth);
+    /** Origins that may send a write with a session cookie. A bearer token needs none. Passed to `requirePrincipal`. */
+    origins?: RequirePrincipalOptions["origins"];
 }
 type AppEnv = {
     Bindings: WorkerEnv;

package/dist/worker.js

@@ -5,7 +5,6 @@ import {
 import {
   ACCEPT_SCOPE,
   CommentsError,
-  PRINCIPAL_KINDS,
   exact,
   invalid,
   stamp
@@ -13,7 +12,8 @@ import {
 
 // src/worker.ts
 import { Hono } from "hono";
-import { StoreConflictError, assertRegion, isScope, parseRegion, hasScope } from "agentic-identity";
+import { StoreConflictError, assertRegion, isScope, parseRegion, hasScope, parsePrincipal } from "agentic-identity";
+import { requirePrincipal } from "agentic-identity/http";
 import { D1_SCHEMA, createD1Store } from "agentic-identity/cloudflare";
 import * as Y from "yjs";
 var READ = "comments:read";
@@ -22,6 +22,7 @@ var WRITE = "comments:write";
 var ADMIN = "comments:admin";
 var DEFAULT_SCOPES = [COMMENT];
 var MIN_TOKEN_BYTES = 32;
+var TOKEN_SHAPE = /^[A-Za-z0-9_-]{1,512}$/;
 var warned = /* @__PURE__ */ new Set();
 function refuse(reason) {
   if (!warned.has(reason)) {
@@ -40,9 +41,13 @@ function contextOf(entry) {
   const who = typeof entry === "string" ? entry : object?.as;
   const cut = typeof who === "string" ? who.indexOf(":") : -1;
   if (typeof who !== "string" || cut < 1 || cut === who.length - 1) return void 0;
-  const kind = who.slice(0, cut);
-  const name = who.slice(cut + 1);
-  if (!PRINCIPAL_KINDS.includes(kind)) return void 0;
+  let kind;
+  let name;
+  try {
+    ({ kind, id: name } = parsePrincipal({ kind: who.slice(0, cut), id: who.slice(cut + 1) }));
+  } catch {
+    return void 0;
+  }
   const given = object?.scopes;
   if (given !== void 0 && !(Array.isArray(given) && given.every(isScope))) return void 0;
   try {
@@ -61,6 +66,7 @@ function createTokenAuth(raw) {
     for (const [token, entry] of Object.entries(parsed)) {
       const context = contextOf(entry);
       if (new TextEncoder().encode(token).length < MIN_TOKEN_BYTES) throw new Error(`a token is shorter than ${MIN_TOKEN_BYTES} bytes`);
+      if (!TOKEN_SHAPE.test(token)) throw new Error("a token holds a character outside A-Z a-z 0-9 _ - or is over 512 bytes");
       if (!context) throw new Error("an entry is not a valid kind:name or { as, scopes }");
       table.set(token, context);
     }
@@ -186,8 +192,12 @@ function createApp(source, options = {}) {
   app2.get("/health", (c) => c.json({ ok: true, pack: "agentic-comments" }));
   app2.use("/api/v1/*", async (c, next) => {
     const auth = typeof options.auth === "function" ? options.auth(c.env ?? {}) : options.auth ?? createTokenAuth(c.env?.AGENTIC_COMMENTS_TOKENS);
-    const context = await auth.authenticate(c.req.raw);
-    if (!context) return fail("UNAUTHENTICATED", "send a valid bearer token", 401);
+    const context = await requirePrincipal(c.req.raw, auth, { origins: options.origins });
+    if (context instanceof Response) {
+      if (context.status === 401) return Response.json({ error: { code: "UNAUTHENTICATED", message: "send a valid bearer token" } }, { status: 401, headers: { "www-authenticate": "Bearer" } });
+      if (context.status === 403) return fail("FORBIDDEN", "this credential may not do this", 403);
+      return fail("INTERNAL", "the credential check is unavailable", context.status);
+    }
     c.set("context", context);
     await next();
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -48,6 +48,10 @@
       "types": "./dist/anchoring.d.ts",
       "import": "./dist/anchoring.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./local": {
       "types": "./dist/local.d.ts",
       "import": "./dist/local.js"
@@ -72,7 +76,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "agentic-identity": "^0.4.0",
+    "agentic-identity": "^0.6.0",
     "hono": "^4.13.14",
     "zod": "^3.25.76"
   },

package/dist/{suggestions-oj8fd-nG.d.ts → suggestions-CvJwo6r4.d.ts}

@@ -1,6 +1,35 @@
 import * as Y from 'yjs';
 import { PrincipalKind } from 'agentic-identity';
 
+/** What a thread keeps about who wrote a message. Scopes never reach storage. */
+interface Author {
+    kind: PrincipalKind;
+    name: string;
+}
+interface StampInput {
+    kind: PrincipalKind;
+    name: string;
+    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
+    scopes?: string[];
+}
+/**
+ * The only author a write accepts. The host makes one from the principal it authenticated, and an
+ * operation never reads an author from its input. An object that `stamp()` did not make is refused,
+ * and a stamped one cannot change.
+ */
+declare class Actor implements Author {
+    readonly kind: PrincipalKind;
+    readonly name: string;
+    readonly scopes: readonly string[];
+    private constructor();
+    static of(input: StampInput): Actor;
+    static is(value: unknown): value is Actor;
+}
+/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
+declare const stamp: (input: StampInput) => Actor;
+/** The label a UI shows. Agent work stays marked as machine-made. */
+declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
+
 /** A Yjs relative position as JSON. It names an item, not an index, so it follows its text. */
 interface RelativePositionJson {
     type?: {
@@ -66,35 +95,6 @@ declare function textOf(type: Y.Text | Y.XmlText): string;
 /** Pin a range of a Yjs text. Later edits by any replica do not move the anchor off its text. */
 declare function textAnchor(type: Y.Text | Y.XmlText, from: number, to: number): TextAnchor;
 
-/** What a thread keeps about who wrote a message. Scopes never reach storage. */
-interface Author {
-    kind: PrincipalKind;
-    name: string;
-}
-interface StampInput {
-    kind: PrincipalKind;
-    name: string;
-    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
-    scopes?: string[];
-}
-/**
- * The only author a write accepts. The host makes one from the principal it authenticated, and an
- * operation never reads an author from its input. An object that `stamp()` did not make is refused,
- * and a stamped one cannot change.
- */
-declare class Actor implements Author {
-    readonly kind: PrincipalKind;
-    readonly name: string;
-    readonly scopes: readonly string[];
-    private constructor();
-    static of(input: StampInput): Actor;
-    static is(value: unknown): value is Actor;
-}
-/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
-declare const stamp: (input: StampInput) => Actor;
-/** The label a UI shows. Agent work stays marked as machine-made. */
-declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
-
 interface Message {
     id: string;
     at: string;