relic-mcp 0.3.2 → 0.4.0

package/dist/relic-mcp.js

@@ -117,6 +117,179 @@ class ContentTooLargeError extends RelicFormatError {
   }
 }
 
+class MalformedCommentError extends RelicFormatError {
+  name = "MalformedCommentError";
+}
+
+class CommentDecryptFailedError extends RelicFormatError {
+  name = "CommentDecryptFailedError";
+  constructor() {
+    super("the comment failed authentication");
+  }
+}
+
+class CommentTooLargeError extends RelicFormatError {
+  field;
+  declaredBytes;
+  limitBytes;
+  name = "CommentTooLargeError";
+  constructor(field, declaredBytes, limitBytes) {
+    super(`comment ${field} is ${declaredBytes} bytes of UTF-8, over the ` + `${limitBytes} cap`);
+    this.field = field;
+    this.declaredBytes = declaredBytes;
+    this.limitBytes = limitBytes;
+  }
+}
+
+// ../relic-format/src/comments.ts
+var COMMENT_INFO = new TextEncoder().encode("relic/comments/v1");
+var COMMENT_NONCE_BYTES = 12;
+var COMMENT_BODY_LIMIT_BYTES = 4096;
+var COMMENT_DISPLAY_NAME_LIMIT_BYTES = 64;
+var COMMENT_ANCHOR_QUOTE_LIMIT_BYTES = 512;
+async function deriveCommentKey(keyBytes) {
+  const material = await crypto.subtle.importKey("raw", toBufferSource(keyBytes), "HKDF", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits({
+    name: "HKDF",
+    hash: "SHA-256",
+    salt: new Uint8Array(0),
+    info: COMMENT_INFO
+  }, material, 128);
+  return crypto.subtle.importKey("raw", bits, { name: "AES-GCM" }, false, [
+    "encrypt",
+    "decrypt"
+  ]);
+}
+async function encryptComment(commentKey, plaintext) {
+  const bodyBytes = new TextEncoder().encode(plaintext.body);
+  if (bodyBytes.length > COMMENT_BODY_LIMIT_BYTES) {
+    throw new CommentTooLargeError("body", bodyBytes.length, COMMENT_BODY_LIMIT_BYTES);
+  }
+  if (plaintext.display_name !== null) {
+    const nameBytes = new TextEncoder().encode(plaintext.display_name).length;
+    if (nameBytes > COMMENT_DISPLAY_NAME_LIMIT_BYTES) {
+      throw new CommentTooLargeError("display_name", nameBytes, COMMENT_DISPLAY_NAME_LIMIT_BYTES);
+    }
+  }
+  if (plaintext.anchor != null && plaintext.anchor.kind === "text") {
+    const quoteBytes = new TextEncoder().encode(plaintext.anchor.quote).length;
+    if (quoteBytes > COMMENT_ANCHOR_QUOTE_LIMIT_BYTES) {
+      throw new CommentTooLargeError("anchor", quoteBytes, COMMENT_ANCHOR_QUOTE_LIMIT_BYTES);
+    }
+  }
+  const encoded = new TextEncoder().encode(JSON.stringify({
+    body: plaintext.body,
+    display_name: plaintext.display_name,
+    ...plaintext.anchor == null ? {} : { anchor: plaintext.anchor }
+  }));
+  const nonce = crypto.getRandomValues(new Uint8Array(COMMENT_NONCE_BYTES));
+  const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: toBufferSource(nonce) }, commentKey, toBufferSource(encoded)));
+  const framed = new Uint8Array(nonce.length + sealed.length);
+  framed.set(nonce, 0);
+  framed.set(sealed, nonce.length);
+  return base64url(framed);
+}
+async function decryptComment(commentKey, ciphertext) {
+  const framed = decodeBase64url(ciphertext);
+  if (framed.length <= COMMENT_NONCE_BYTES) {
+    throw new MalformedCommentError(`comment is ${framed.length} bytes, too short to carry a ` + `${COMMENT_NONCE_BYTES}-byte nonce and a tag`);
+  }
+  let opened;
+  try {
+    opened = new Uint8Array(await crypto.subtle.decrypt({
+      name: "AES-GCM",
+      iv: toBufferSource(framed.subarray(0, COMMENT_NONCE_BYTES))
+    }, commentKey, toBufferSource(framed.subarray(COMMENT_NONCE_BYTES))));
+  } catch {
+    throw new CommentDecryptFailedError;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(opened));
+  } catch {
+    throw new MalformedCommentError("comment plaintext is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new MalformedCommentError("comment plaintext is not a JSON object");
+  }
+  const fields = parsed;
+  const unknown = Object.keys(fields).filter((key) => key !== "body" && key !== "display_name" && key !== "anchor");
+  if (unknown.length > 0) {
+    throw new MalformedCommentError(`comment carries unknown field(s): ${unknown.join(", ")}`);
+  }
+  const body = fields["body"];
+  if (typeof body !== "string") {
+    throw new MalformedCommentError("comment body is missing or not a string");
+  }
+  const displayName = fields["display_name"];
+  if (displayName !== null && typeof displayName !== "string") {
+    throw new MalformedCommentError("comment display_name is present and is neither a string nor null");
+  }
+  return {
+    body,
+    display_name: displayName,
+    anchor: parseAnchor(fields["anchor"])
+  };
+}
+function parseAnchor(value) {
+  if (value === undefined)
+    return null;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new MalformedCommentError("comment anchor is not an object");
+  }
+  const anchor = value;
+  const kind = anchor["kind"];
+  if (kind === "text") {
+    const quote = anchor["quote"];
+    if (typeof quote !== "string" || quote.length === 0) {
+      throw new MalformedCommentError("text anchor quote is missing");
+    }
+    const extra = Object.keys(anchor).filter((key) => key !== "kind" && key !== "quote");
+    if (extra.length > 0) {
+      throw new MalformedCommentError(`text anchor carries unknown field(s): ${extra.join(", ")}`);
+    }
+    return { kind: "text", quote };
+  }
+  if (kind === "pin") {
+    const x = anchor["x"];
+    const y = anchor["y"];
+    if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || x < 0 || x > 1 || y < 0 || y > 1) {
+      throw new MalformedCommentError("pin anchor is out of unit range");
+    }
+    const extra = Object.keys(anchor).filter((key) => key !== "kind" && key !== "x" && key !== "y");
+    if (extra.length > 0) {
+      throw new MalformedCommentError(`pin anchor carries unknown field(s): ${extra.join(", ")}`);
+    }
+    return { kind: "pin", x, y };
+  }
+  throw new MalformedCommentError("comment anchor kind is not text or pin");
+}
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeBase64url(encoded) {
+  if (!/^[A-Za-z0-9_-]*$/.test(encoded)) {
+    throw new MalformedCommentError("comment is not unpadded base64url");
+  }
+  const padded = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  let binary;
+  try {
+    binary = atob(padded.padEnd(Math.ceil(padded.length / 4) * 4, "="));
+  } catch {
+    throw new MalformedCommentError("comment is not decodable base64url");
+  }
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+function toBufferSource(bytes) {
+  return bytes.slice().buffer;
+}
 // ../relic-format/src/envelope.ts
 var MAX_FILENAME_BYTES = 1024;
 var MAX_MIMETYPE_BYTES = 255;
@@ -237,17 +410,17 @@ function recordCapacity(rs) {
 var CEK_INFO = new TextEncoder().encode("Content-Encoding: aes128gcm\x00");
 var NONCE_INFO = new TextEncoder().encode("Content-Encoding: nonce\x00");
 async function deriveKeys(ikm, salt) {
-  const material = await crypto.subtle.importKey("raw", toBufferSource(ikm), "HKDF", false, ["deriveBits"]);
+  const material = await crypto.subtle.importKey("raw", toBufferSource2(ikm), "HKDF", false, ["deriveBits"]);
   const cekBits = await crypto.subtle.deriveBits({
     name: "HKDF",
     hash: "SHA-256",
-    salt: toBufferSource(salt),
+    salt: toBufferSource2(salt),
     info: CEK_INFO
   }, material, 128);
   const nonceBits = await crypto.subtle.deriveBits({
     name: "HKDF",
     hash: "SHA-256",
-    salt: toBufferSource(salt),
+    salt: toBufferSource2(salt),
     info: NONCE_INFO
   }, material, 96);
   const cek = await crypto.subtle.importKey("raw", cekBits, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
@@ -282,10 +455,10 @@ async function encryptRecord(keys, seq, data, isLast, targetDataBytes = data.len
   const plaintext = new Uint8Array(targetDataBytes + DELIMITER_BYTES);
   plaintext.set(data, 0);
   plaintext[data.length] = isLast ? 2 : 1;
-  const sealed = await crypto.subtle.encrypt({ name: "AES-GCM", iv: toBufferSource(recordNonce(keys.nonceBase, seq)) }, keys.cek, toBufferSource(plaintext));
+  const sealed = await crypto.subtle.encrypt({ name: "AES-GCM", iv: toBufferSource2(recordNonce(keys.nonceBase, seq)) }, keys.cek, toBufferSource2(plaintext));
   return new Uint8Array(sealed);
 }
-function toBufferSource(bytes) {
+function toBufferSource2(bytes) {
   return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
 
@@ -1033,9 +1206,25 @@ async function postJson(deps, url, body) {
   } catch (error) {
     throw new PublishError("service_unreachable", `could not reach ${url}: ${error.message}`);
   }
-  const parsed = await response.json().catch(() => ({}));
+  const parsed = await readJson(response);
+  return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+}
+async function getJson(deps, url) {
+  let response;
+  try {
+    response = await deps.fetch(url);
+  } catch (error) {
+    throw new PublishError("service_unreachable", `could not reach ${url}: ${error.message}`);
+  }
+  return readJson(response);
+}
+async function readJson(response) {
+  const parsed = await response.json().catch(() => {
+    return;
+  });
   if (!response.ok) {
-    throw new ServerRefusal(String(parsed["code"] ?? "unknown"), response.status, parsed);
+    const problem = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    throw new ServerRefusal(String(problem["code"] ?? "unknown"), response.status, problem);
   }
   return parsed;
 }
@@ -1104,6 +1293,112 @@ function guessMimetype(filename, rendererClass) {
   return CLASS_FALLBACK[rendererClass];
 }
 
+// src/comments.ts
+async function readComments(relicId, deps) {
+  const state = await localState(relicId);
+  const listed = await getJson(deps, `${deps.serviceOrigin}/api/relics/${relicId}/comments`);
+  if (!Array.isArray(listed)) {
+    throw new PublishError("app_response_unusable", "the comment list did not come back as a JSON array, so there is no " + "way to tell an empty conversation from an unreadable response", { relic_id: relicId, leg: "comments" });
+  }
+  const commentKey = await deriveCommentKey(decodeKey(state.key));
+  const comments2 = [];
+  let unreadable = 0;
+  for (const [index, entry] of listed.entries()) {
+    const row = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : {};
+    const commentId = typeof row["comment_id"] === "string" ? row["comment_id"] : `unidentified-${index}`;
+    const author = typeof row["author"] === "string" ? row["author"] : "unknown";
+    const createdAt = typeof row["created_at"] === "string" ? row["created_at"] : "unknown";
+    const ciphertext = row["ciphertext"];
+    if (typeof ciphertext !== "string") {
+      unreadable += 1;
+      comments2.push({
+        comment_id: commentId,
+        author,
+        created_at: createdAt,
+        display_name: null,
+        body: null,
+        readable: false,
+        unreadable_reason: "the row carried no ciphertext"
+      });
+      continue;
+    }
+    try {
+      const plaintext = await decryptComment(commentKey, ciphertext);
+      comments2.push({
+        comment_id: commentId,
+        author,
+        created_at: createdAt,
+        display_name: plaintext.display_name,
+        body: plaintext.body,
+        readable: true,
+        unreadable_reason: null
+      });
+    } catch (error) {
+      unreadable += 1;
+      comments2.push({
+        comment_id: commentId,
+        author,
+        created_at: createdAt,
+        display_name: null,
+        body: null,
+        readable: false,
+        unreadable_reason: `it did not decrypt under this relic's comment key: ${error.message}`
+      });
+    }
+  }
+  return {
+    relic_id: relicId,
+    count: comments2.length,
+    unreadable_count: unreadable,
+    comments: comments2
+  };
+}
+async function postComment(input, deps) {
+  const state = await localState(input.relic_id);
+  const bodyBytes = new TextEncoder().encode(input.body).length;
+  if (input.body.trim().length === 0) {
+    throw new PublishError("local_comment_body_empty", "a comment needs a body. An empty one is attributable noise nobody can " + "answer.");
+  }
+  if (bodyBytes > COMMENT_BODY_LIMIT_BYTES) {
+    throw new PublishError("local_comment_body_too_long", `the comment body is ${bodyBytes} bytes of UTF-8 and the limit is ` + `${COMMENT_BODY_LIMIT_BYTES}. Shorten it; a truncated comment would ` + "change what it says.", { body_bytes: bodyBytes, limit_bytes: COMMENT_BODY_LIMIT_BYTES });
+  }
+  const displayName = input.display_name ?? null;
+  if (displayName !== null) {
+    const nameBytes = new TextEncoder().encode(displayName).length;
+    if (nameBytes > COMMENT_DISPLAY_NAME_LIMIT_BYTES) {
+      throw new PublishError("local_comment_name_too_long", `the display name is ${nameBytes} bytes of UTF-8 and the limit is ` + `${COMMENT_DISPLAY_NAME_LIMIT_BYTES}.`, { name_bytes: nameBytes, limit_bytes: COMMENT_DISPLAY_NAME_LIMIT_BYTES });
+    }
+  }
+  const commentKey = await deriveCommentKey(decodeKey(state.key));
+  const ciphertext = await encryptComment(commentKey, {
+    body: input.body,
+    display_name: displayName
+  });
+  const posted = await postJson(deps, `${deps.serviceOrigin}/api/relics/${input.relic_id}/comments`, { publish_token: state.publish_token, ciphertext });
+  return {
+    relic_id: input.relic_id,
+    comment_id: String(posted["comment_id"]),
+    author: String(posted["author"]),
+    created_at: String(posted["created_at"])
+  };
+}
+async function localState(relicId) {
+  if (!isValidRelicId(relicId)) {
+    throw new PublishError("no_local_publish_state", `"${relicId}" is not a relic id. These tools take the 26-character id ` + "the original publish returned, never the share URL: the URL carries " + "the key in its fragment, and passing it would put the key in this " + "transcript for nothing.");
+  }
+  try {
+    const loaded = await loadPublishState(relicId);
+    if (loaded === undefined) {
+      throw new PublishError("no_local_publish_state", `relic ${relicId} was published from another machine, so its ` + "comments can be neither read nor written here. The key that " + "decrypts a comment and the publish token that authorizes one live " + "only on the machine that made the first publish, and neither can " + "be reconstructed from the link or from the service. Open the " + "relic's own page to read its comments, or ask whoever published it.");
+    }
+    return loaded;
+  } catch (error) {
+    if (error instanceof PublishError)
+      throw error;
+    throw new PublishError("local_state_unreadable", error.message);
+  }
+}
+
 // src/republish.ts
 async function republish(input, deps) {
   if (!isValidRelicId(input.relic_id)) {
@@ -1162,11 +1457,15 @@ var TOOL_NAME = "relic_publish";
 var DESCRIBE_TOOL_NAME = "relic_describe_client";
 var REPUBLISH_TOOL_NAME = "relic_republish";
 var LOOKUP_TOOL_NAME = "relic_lookup_source";
+var READ_COMMENTS_TOOL_NAME = "relic_read_comments";
+var COMMENT_TOOL_NAME = "relic_comment";
+var COMMENT_MACHINE_BOUNDARY = "Only works for a relic this machine published: the comment key is derived " + "from that relic's key, which lives in local publish state and nowhere the " + "service can reach.";
 var MAX_TTL_DAYS = 3650;
+var VERSION_HISTORY_DISCLOSURE = "Anyone holding a relic's link can fetch every version it has ever held, " + "so republishing does not withdraw earlier content.";
 var TOOL_DEFINITION = {
   name: TOOL_NAME,
   title: "Publish a relic",
-  description: "Encrypt a file on this machine and publish it as a new relic, returning " + "a shareable URL. Publishing an update this way costs a second URL that " + "nobody holding the first one will ever see; use relic_republish instead " + "so the existing URL keeps working. The encryption key is generated " + "locally and never sent to the service. Takes a filesystem path, never " + "inline content.",
+  description: "Encrypt a file on this machine and publish it as a new relic, returning " + "a shareable URL. Publishing an update this way costs a second URL that " + "nobody holding the first one will ever see; use relic_republish instead " + "so the existing URL keeps working. " + VERSION_HISTORY_DISCLOSURE + " The encryption key is generated locally and never sent to the service. " + "Takes a filesystem path, never " + "inline content.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1227,7 +1526,7 @@ var TOOL_DEFINITION = {
 var REPUBLISH_TOOL_DEFINITION = {
   name: REPUBLISH_TOOL_NAME,
   title: "Republish a relic",
-  description: "Publish a new version of a relic this machine originally published, " + "encrypting under the same key so the existing share URL keeps working. " + "Only possible from the machine that holds the relic's key and publish " + "token; a relic that was taken down can never be revived.",
+  description: "Publish a new version of a relic this machine originally published, " + "encrypting under the same key so the existing share URL keeps working. " + VERSION_HISTORY_DISCLOSURE + " Only possible from the machine that holds the relic's key and publish " + "token; a relic that was taken down can never be revived.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1336,6 +1635,99 @@ var LOOKUP_TOOL_DEFINITION = {
     additionalProperties: false
   }
 };
+var READ_COMMENTS_TOOL_DEFINITION = {
+  name: READ_COMMENTS_TOOL_NAME,
+  title: "Read a relic's comments",
+  description: "Read the comments people have left on a relic, oldest first, decrypted " + "on this machine. Use it before changing content somebody was asked to " + "review, and after sharing a link, because a comment is the only way a " + "reader can answer back. " + COMMENT_MACHINE_BOUNDARY + " Takes the relic id, never the share URL: the URL carries the key in " + "its fragment. A comment that will not decrypt is returned marked " + "unreadable rather than dropped, so a shortened list never reads as " + "agreement.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      relic_id: {
+        type: "string",
+        description: "The 26-character relic id the original publish returned."
+      }
+    },
+    required: ["relic_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      relic_id: { type: "string" },
+      count: { type: "integer", minimum: 0 },
+      unreadable_count: {
+        type: "integer",
+        minimum: 0,
+        description: "How many of `count` did not decrypt. Above zero means part of the " + "conversation is unread, not absent."
+      },
+      comments: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            comment_id: { type: "string" },
+            author: {
+              type: "string",
+              description: 'The commenter’s verified email address, or "publisher" ' + "for a comment written with a publish token."
+            },
+            created_at: { type: "string" },
+            display_name: { type: ["string", "null"] },
+            body: { type: ["string", "null"] },
+            readable: { type: "boolean" },
+            unreadable_reason: { type: ["string", "null"] }
+          },
+          required: [
+            "comment_id",
+            "author",
+            "created_at",
+            "display_name",
+            "body",
+            "readable",
+            "unreadable_reason"
+          ],
+          additionalProperties: false
+        }
+      }
+    },
+    required: ["relic_id", "count", "unreadable_count", "comments"],
+    additionalProperties: false
+  }
+};
+var COMMENT_TOOL_DEFINITION = {
+  name: COMMENT_TOOL_NAME,
+  title: "Comment on a relic",
+  description: "Leave a comment on a relic this machine published, encrypted here so " + "the service stores ciphertext it cannot read. Everyone holding the " + "link sees it. Attribution is the publish token, so the comment is " + 'attributed to "publisher" rather than to an email address: an agent has ' + "no mailbox and cannot verify one. That is attribution and not " + "authorization. " + COMMENT_MACHINE_BOUNDARY + " Takes the relic id, never the share URL.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      relic_id: {
+        type: "string",
+        description: "The 26-character relic id the original publish returned."
+      },
+      body: {
+        type: "string",
+        description: "The comment text, up to 4096 bytes of UTF-8. It is encrypted " + "before it leaves this machine."
+      },
+      display_name: {
+        type: "string",
+        description: "Optional. A name shown beside the comment, up to 64 bytes of " + "UTF-8. It aliases the attribution for presentation and never " + "replaces it."
+      }
+    },
+    required: ["relic_id", "body"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      relic_id: { type: "string" },
+      comment_id: { type: "string" },
+      author: { type: "string" },
+      created_at: { type: "string" }
+    },
+    required: ["relic_id", "comment_id", "author", "created_at"],
+    additionalProperties: false
+  }
+};
 var DESCRIBE_TOOL_DEFINITION = {
   name: DESCRIBE_TOOL_NAME,
   title: "Describe the Relic client",
@@ -1346,7 +1738,7 @@ var DESCRIBE_TOOL_DEFINITION = {
     additionalProperties: false
   }
 };
-var SERVER_VERSION = "0.3.2";
+var SERVER_VERSION = "0.4.0";
 var SERVER_INFO = {
   name: "relic",
   title: "Relic",
@@ -1355,13 +1747,14 @@ var SERVER_INFO = {
 var CAPABILITIES = { tools: {} };
 var INSTRUCTIONS = `Relic encrypts a file on this machine and uploads only ciphertext. The key lives in the URL fragment, which browsers never send to a server.
 
-Five things that change how you should act:
+Six things that change how you should act:
 
 1. The link is the credential. Anyone holding it, fragment included, can read the file. Do not paste it into a tracker, a log, or a public channel.
 2. Publishing puts the key in this transcript. That is structural rather than a defect, and worth saying plainly when you hand the link over.
-3. If a source was published before, use relic_republish so its URL keeps working. Publishing it as new costs a second URL that nobody holding the first one will ever see. relic_publish refuses by default, relic_lookup_source recovers the id, and force_new is only for a deliberate second link.
+3. Check existing sources with relic_lookup_source. Use relic_republish when found; relic_publish otherwise costs a second URL. ${VERSION_HISTORY_DISCLOSURE}
 4. A relic can be republished only from the machine that published it, which is where its key and publish token are stored. Anywhere else it refuses, and no retry changes that.
-5. Rendered HTML and JSX run in an isolated frame with no network access. Inline the styles, scripts, fonts, and images a page needs, because a CDN reference renders as nothing. Decide that before you write the file.`;
+5. Rendered HTML and JSX run in an isolated frame with no network access. Inline the styles, scripts, fonts, and images a page needs, because a CDN reference renders as nothing. Decide that before you write the file.
+6. People can comment on a relic. Read them with relic_read_comments before you change reviewed content, and answer with relic_comment. Both take the relic id, work only on the machine that published, and attribute you as the publisher.`;
 async function handleMessage(message, deps) {
   if (message.id === undefined)
     return;
@@ -1407,6 +1800,8 @@ async function handleMessage(message, deps) {
             TOOL_DEFINITION,
             LOOKUP_TOOL_DEFINITION,
             REPUBLISH_TOOL_DEFINITION,
+            READ_COMMENTS_TOOL_DEFINITION,
+            COMMENT_TOOL_DEFINITION,
             DESCRIBE_TOOL_DEFINITION
           ]
         }
@@ -1437,6 +1832,8 @@ async function callTool(id2, params, deps) {
           plaintext_transmitted_to_service: false,
           ciphertext_destination: "object storage, via a signed URL",
           local_publish_state: "relic id, source identity, key, and publish token per relic, " + "written 0600 under the user config directory; key and token " + "are never printed or sent",
+          comment_encryption: "AES-128-GCM under a key derived from the relic key with a " + "distinct HKDF label, so comment bodies reach the service as " + "ciphertext and the URL fragment is unchanged",
+          comment_attribution: 'the publish token, reported by the service as "publisher"; the ' + "operator learns which identity commented on which relic and when",
           service_origin: deps.serviceOrigin
         },
         isError: false
@@ -1449,6 +1846,12 @@ async function callTool(id2, params, deps) {
   if (params["name"] === REPUBLISH_TOOL_NAME) {
     return callRepublish(id2, params, deps);
   }
+  if (params["name"] === READ_COMMENTS_TOOL_NAME) {
+    return callReadComments(id2, params, deps);
+  }
+  if (params["name"] === COMMENT_TOOL_NAME) {
+    return callComment(id2, params, deps);
+  }
   if (params["name"] !== TOOL_NAME) {
     return errorResponse(id2, ERROR_CODES.invalidParams, `unknown tool: ${String(params["name"])}`);
   }
@@ -1486,7 +1889,8 @@ async function callTool(id2, params, deps) {
 
 ` + (result.relic_expires_at === null ? "It does not expire; it is kept until it is deleted. " : `Expires ${result.relic_expires_at}. `) + "Anyone with this link, " + "including its fragment, can read the file. The key is in the " + "fragment and it is now in this transcript. This machine can " + `republish it later; the link will not change.
 ` + isolationNote(result.renderer_class) + `What Relic knows: ${result.disclosure_url}`
-          }
+          },
+          { type: "text", text: VERSION_HISTORY_DISCLOSURE }
         ],
         structuredContent: result,
         isError: false
@@ -1564,6 +1968,63 @@ async function callRepublish(id2, params, deps) {
 
 ` + (result.relic_expires_at === null ? "The relic does not expire; it is kept until it is deleted." : `Expires ${result.relic_expires_at}.`) + `
 ` + `What Relic knows: ${result.disclosure_url}`
+          },
+          { type: "text", text: VERSION_HISTORY_DISCLOSURE }
+        ],
+        structuredContent: result,
+        isError: false
+      }
+    };
+  } catch (error) {
+    return { jsonrpc: "2.0", id: id2, result: toolError(error) };
+  }
+}
+async function callReadComments(id2, params, deps) {
+  const args = params["arguments"] ?? {};
+  const relicId = args["relic_id"];
+  if (typeof relicId !== "string" || relicId.length === 0) {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`relic_id` is required and must be a string");
+  }
+  try {
+    const result = await readComments(relicId, deps);
+    return {
+      jsonrpc: "2.0",
+      id: id2,
+      result: {
+        content: [{ type: "text", text: commentTranscript(result) }],
+        structuredContent: result,
+        isError: false
+      }
+    };
+  } catch (error) {
+    return { jsonrpc: "2.0", id: id2, result: toolError(error) };
+  }
+}
+async function callComment(id2, params, deps) {
+  const args = params["arguments"] ?? {};
+  const relicId = args["relic_id"];
+  if (typeof relicId !== "string" || relicId.length === 0) {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`relic_id` is required and must be a string");
+  }
+  const body = args["body"];
+  if (typeof body !== "string") {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`body` is required and must be a string");
+  }
+  const displayName = args["display_name"];
+  if (displayName !== undefined && typeof displayName !== "string") {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`display_name` must be a string or omitted");
+  }
+  try {
+    const result = await postComment({ relic_id: relicId, body, display_name: displayName }, deps);
+    return {
+      jsonrpc: "2.0",
+      id: id2,
+      result: {
+        content: [
+          {
+            type: "text",
+            text: `Commented on relic ${result.relic_id} as ${result.author}.
+` + "Everyone holding the link sees it. The service stored " + "ciphertext it cannot read, and it knows that this address " + "commented on this relic at this time."
           }
         ],
         structuredContent: result,
@@ -1574,6 +2035,23 @@ async function callRepublish(id2, params, deps) {
     return { jsonrpc: "2.0", id: id2, result: toolError(error) };
   }
 }
+function commentTranscript(result) {
+  if (result.count === 0) {
+    return `No comments on relic ${result.relic_id} yet.`;
+  }
+  const lines = result.comments.map((comment) => {
+    const who = comment.display_name === null ? comment.author : `${comment.display_name} (${comment.author})`;
+    return comment.readable ? `${comment.created_at} ${who}:
+${comment.body}` : `${comment.created_at} ${who}:
+[unreadable: ${comment.unreadable_reason}]`;
+  });
+  const header = result.unreadable_count === 0 ? `${result.count} comment(s) on relic ${result.relic_id}, oldest first.` : `${result.count} comment(s) on relic ${result.relic_id}, oldest ` + `first. ${result.unreadable_count} did not decrypt and are shown as ` + "unreadable rather than dropped, so treat this conversation as " + "partially unread.";
+  return `${header}
+
+${lines.join(`
+
+`)}`;
+}
 function parseTtlDays(raw) {
   if (raw === undefined || raw === null)
     return { ok: true, days: undefined };
@@ -1584,7 +2062,8 @@ function parseTtlDays(raw) {
 }
 var REFUSAL_GUIDANCE = {
   invalid_publish_token: "The publish token this machine holds for that relic was rejected. It " + "is issued once, at first publish, and never changes, so a rejection " + "means the local record no longer matches the service's. The relic can " + "still be read at its existing link, but it cannot be republished from " + "here.",
-  relic_removed: "That relic was taken down. A takedown is permanent: republishing " + "cannot revive it, whatever token is presented. Publish the content as " + "a new relic instead."
+  relic_removed: "That relic was taken down. A takedown is permanent: republishing " + "cannot revive it, whatever token is presented. Publish the content as " + "a new relic instead.",
+  comment_rate_limited: "The service is rate limiting comments on that relic. The refusal " + "carries retry_after_seconds; wait it out rather than retrying in a " + "loop, which only extends the limit."
 };
 function toolError(error) {
   if (error instanceof PublishError) {
@@ -1609,7 +2088,7 @@ ${guidance}`)
     };
   }
   return {
-    content: [{ type: "text", text: `publish failed: ${String(error)}` }],
+    content: [{ type: "text", text: `the call failed: ${String(error)}` }],
     structuredContent: { code: "unknown" },
     isError: true
   };
@@ -1647,6 +2126,17 @@ service ever holds, and neither secret is ever printed or logged. Deleting the
 file changes nothing for existing links; it only ends this machine's ability
 to update those relics.
 
+What happens with comments: a comment body is encrypted here too, under a key
+derived from that relic's key with a distinct HKDF label, so the service
+stores comment ciphertext it cannot read and the URL fragment does not change.
+Reading comments needs that key, and writing one is authorized by the publish
+token, so both work only on the machine that published. A comment this client
+writes is attributed to the publisher rather than an email address, because
+an agent has no mailbox to verify. What the operator does learn is who
+commented on which relic and when: for a person that is a verified email
+address, and that association is a real cost the content's encryption does
+not cover.
+
 What this does NOT protect against: the key is returned to your agent in the
 URL, so it enters the model's context and your session transcript. That is
 structural, not a defect. Anyone who can read this conversation can open the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relic-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Publish a file as an encrypted relic. The key is generated on your machine and never sent to the service.",
   "license": "MIT",
   "type": "module",