agentic-comments 0.5.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

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-WQHJNHAR.js → chunk-REFQNIEP.js}

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

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

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-WQHJNHAR.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-WQHJNHAR.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-JMEXA2RI.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/index.js

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

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-JMEXA2RI.js → mcp-XUV3RPOO.js}

@@ -1,8 +1,8 @@
 import {
   createMcpServer,
   startMcp
-} from "./chunk-ABXAPWXD.js";
-import "./chunk-WQHJNHAR.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-ABXAPWXD.js";
+} from "./chunk-TFRLOBJW.js";
 import {
   VERSION
-} from "./chunk-WQHJNHAR.js";
+} from "./chunk-REFQNIEP.js";
 import "./chunk-NQWRFKJ6.js";
 import "./chunk-BSNBDKR2.js";
 

package/dist/worker.d.ts

@@ -1,5 +1,6 @@
 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-CvJwo6r4.js';
 import { C as CommentsService } from './service-hpWbnSmc.js';
@@ -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.5.0",
+  "version": "0.5.1",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -76,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"
   },