relic-mcp 0.3.2 → 0.4.0

package/skills/relic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: relic
-description: Publish a local file as an encrypted, shareable link when someone outside this session needs to see it. Use when the user says "share this", "send this to X", "publish this", "give me a link for this", "make this shareable", or has just been handed a generated report, HTML page, deck, image, or export and needs it somewhere a person can open. Also covers republishing a new version of an existing relic, what the recipient sees, how long a link lives, and what the service can and cannot read.
+description: Publish a local file as an encrypted, shareable link when someone outside this session needs to see it. Use when the user says "share this", "send this to X", "publish this", "give me a link for this", "make this shareable", or has just been handed a generated report, HTML page, deck, image, or export and needs it somewhere a person can open. Also covers republishing a new version of an existing relic, reading the comments people leave on one and answering them, what the recipient sees, how long a link lives, and what the service can and cannot read.
 ---
 
 # Relic
@@ -39,6 +39,11 @@ Do not publish an update as a new relic. That costs a second URL that nobody
 holding the first one will ever see. `relic_publish` enforces this: when local
 state matches the source, it refuses and points to `relic_republish`.
 
+Anyone holding a relic's link can fetch every version it has ever held, so
+republishing does not withdraw earlier content. Republishing moves the artifact
+forward without retracting what came before. Deleting the relic still removes
+every version.
+
 Optional arguments worth knowing:
 
 - `filename` overrides the display name shown to the recipient.
@@ -81,6 +86,50 @@ Two things to know before promising an update:
 A relic's lifetime is set at its first publish and carries across versions
 unchanged.
 
+## Comments
+
+People can comment on a relic, and that is the only way a reader can answer
+back: there is no reply-to, no dashboard, and no notification. So read them.
+
+```
+relic_read_comments(relic_id: "0a2c...")
+```
+
+Read them **before** you change content somebody was asked to review, and read
+them again after you hand a link over and come back to the task. A comment
+that nobody read is the same as a comment nobody left, except somebody spent
+the effort.
+
+Answer with:
+
+```
+relic_comment(relic_id: "0a2c...", body: "Fixed the chart, republished as version 3.")
+```
+
+Four things to know:
+
+- **Both work only on the machine that published the relic.** The comment key
+  is derived from that relic's key, which lives in the same local 0600 file as
+  the publish token. On any other machine they refuse, for the same reason
+  `relic_republish` does, and no retry changes it.
+- **Pass the relic id, never the URL.** The URL carries the key in its
+  fragment. Passing it would put the key in the transcript again for nothing.
+  The tools refuse a URL and say so.
+- **Your comment is attributed to the publisher, not to a person.** A human
+  commenter verifies an email address through a magic link and that address is
+  their identity. You have no mailbox, so the publish token stands in and the
+  comment reads as `publisher`. Optional `display_name` puts a label beside it;
+  it decorates the attribution and never replaces it.
+- **A comment that will not decrypt comes back marked unreadable**, with a
+  count. That is not noise to filter out: it means part of the conversation is
+  unread. Say so rather than acting as though the readable ones are all of it.
+
+Comment bodies are encrypted on this machine, so the service stores ciphertext
+it cannot read. What it does learn is who commented on which relic and when,
+which for a human commenter is a verified email address. Worth saying plainly
+if somebody asks what commenting costs them: the content stays private and the
+participation does not.
+
 ## Say this when you hand over the link
 
 **The key is in the URL, and the URL is now in the transcript.** Anyone with

package/src/comments.ts

@@ -0,0 +1,286 @@
+/**
+ * Comments, from an agent's seat.
+ *
+ * The feature exists so a person can leave a comment and an agent can read it
+ * back and act on it. The agent's half has two constraints the person's does
+ * not, and both are structural rather than stylistic.
+ *
+ * **An agent cannot receive email.** `docs/frame.md` makes a verified email
+ * address the commenter identity, and verification runs through a magic link,
+ * which needs a mailbox. There is no mailbox here. The publish token already
+ * proves this machine published the relic, so it stands as the agent's
+ * identity and the service attributes the comment to `publisher`. That is
+ * attribution, never authorization: the same non-goal entry says verified
+ * email buys attribution and not entitlement, and a bearer token buys less.
+ *
+ * **The share URL is never an argument.** The fragment is the key, so a tool
+ * accepting the URL would put the key in the transcript on every read, which
+ * is the one disclosure `spec/publish.md` section 5 spends deliberately and
+ * exactly once, at publish. These tools take the relic id and read the key
+ * from local publish state instead, which draws the same machine boundary
+ * republish already draws: only the machine that published can comment on a
+ * relic or read its comments here.
+ *
+ * The comment key is derived from the fragment's key bytes under a distinct
+ * HKDF `info`, so it is independent of the container key by construction, and
+ * the fragment does not change. `spec/format.md` 2.1 fixes the fragment at
+ * the marker and the key, and a third field would cost a version bump.
+ */
+
+import {
+  COMMENT_BODY_LIMIT_BYTES,
+  COMMENT_DISPLAY_NAME_LIMIT_BYTES,
+  decodeKey,
+  decryptComment,
+  deriveCommentKey,
+  encryptComment,
+  isValidRelicId,
+} from '@relic/format';
+import {
+  getJson,
+  type PublishDeps,
+  PublishError,
+  postJson,
+} from './publish.ts';
+import { loadPublishState, type PublishState } from './state.ts';
+
+/** One comment as an agent reads it. */
+export interface CommentRecord {
+  readonly comment_id: string;
+  /**
+   * The verified email address of a human commenter, or the literal
+   * `publisher` for a comment authorized by a publish token. Returned as the
+   * service gave it: `docs/frame.md` makes the address the identity, so a
+   * display name aliases it and never replaces it.
+   */
+  readonly author: string;
+  readonly created_at: string;
+  /** The commenter's chosen alias, when they set one. Decoration, not identity. */
+  readonly display_name: string | null;
+  /** Null exactly when `readable` is false. */
+  readonly body: string | null;
+  readonly readable: boolean;
+  /** Null exactly when `readable` is true. */
+  readonly unreadable_reason: string | null;
+}
+
+export interface ReadCommentsResult {
+  readonly relic_id: string;
+  readonly count: number;
+  /**
+   * Comments the comment key did not open. Reported rather than dropped: a
+   * silently shortened list reads as agreement, and an agent acting on
+   * "nobody objected" when somebody did is the failure this member prevents.
+   */
+  readonly unreadable_count: number;
+  readonly comments: readonly CommentRecord[];
+}
+
+export interface CommentResult {
+  readonly relic_id: string;
+  readonly comment_id: string;
+  readonly author: string;
+  readonly created_at: string;
+}
+
+export interface CommentInput {
+  readonly relic_id: string;
+  readonly body: string;
+  readonly display_name?: string | undefined;
+}
+
+export async function readComments(
+  relicId: string,
+  deps: PublishDeps
+): Promise<ReadCommentsResult> {
+  const state = await localState(relicId);
+
+  // No credential on this read. Anyone holding the link can already fetch the
+  // ciphertext, and the bodies are ciphertext the service cannot open, so
+  // authorizing it would gate nothing and cost the token an exposure.
+  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 comments: CommentRecord[] = [];
+  let unreadable = 0;
+
+  for (const [index, entry] of listed.entries()) {
+    const row =
+      typeof entry === 'object' && entry !== null && !Array.isArray(entry)
+        ? (entry as Record<string, unknown>)
+        : {};
+    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;
+      comments.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);
+      comments.push({
+        comment_id: commentId,
+        author,
+        created_at: createdAt,
+        display_name: plaintext.display_name,
+        body: plaintext.body,
+        readable: true,
+        unreadable_reason: null,
+      });
+    } catch (error) {
+      // One comment that will not open must not hide the ones that will, and
+      // it must not vanish either. It comes back named, with the reason.
+      unreadable += 1;
+      comments.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 as Error).message
+        }`,
+      });
+    }
+  }
+
+  return {
+    relic_id: relicId,
+    count: comments.length,
+    unreadable_count: unreadable,
+    comments,
+  };
+}
+
+export async function postComment(
+  input: CommentInput,
+  deps: PublishDeps
+): Promise<CommentResult> {
+  const state = await localState(input.relic_id);
+
+  // The caps belong to the envelope, so they are enforced against its numbers
+  // rather than a second copy of them, and enforced before encryption so the
+  // refusal names the limit instead of a cipher failure.
+  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,
+  });
+
+  // The token travels in the body, where the republish grant already puts it,
+  // so the two write paths authorize the same way and neither invents a
+  // header the service has to learn.
+  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']),
+  };
+}
+
+/**
+ * The machine boundary, checked before anything touches the network.
+ *
+ * Both tools need the key, and the write needs the publish token too. Neither
+ * can be reconstructed from the link or from the service, so a relic this
+ * machine never published is refused here rather than after a round trip that
+ * could only end the same way.
+ */
+async function localState(relicId: string): Promise<PublishState> {
+  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) {
+    // State-file damage is not "published elsewhere"; naming it as that would
+    // send someone hunting the wrong machine.
+    if (error instanceof PublishError) throw error;
+    throw new PublishError('local_state_unreadable', (error as Error).message);
+  }
+}

package/src/publish.ts

@@ -36,6 +36,11 @@ import {
  * app-server status, so they get codes here, and these never collide with the
  * server's. The state codes join them for the same reason: the publish state
  * is this machine's alone, so its failures are this machine's to report.
+ *
+ * The `local_comment_*` codes take the `local_` prefix `spec/publish.md` 2.2
+ * reserves for a client-side refusal with no leg, rather than a bare
+ * `comment_` one. The service owns its own comment refusals, and an
+ * unprefixed name here would eventually collide with one of them.
  */
 export type ClientCode =
   | 'source_not_found'
@@ -49,7 +54,11 @@ export type ClientCode =
   | 'grant_missing_publish_token'
   | 'no_local_publish_state'
   | 'local_state_unreadable'
-  | 'local_state_write_failed';
+  | 'local_state_write_failed'
+  | 'local_comment_body_empty'
+  | 'local_comment_body_too_long'
+  | 'local_comment_name_too_long'
+  | 'app_response_unusable';
 
 export class PublishError extends Error {
   override readonly name = 'PublishError';
@@ -457,18 +466,60 @@ export async function postJson(
     );
   }
 
-  const parsed = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
+  const parsed = await readJson(response);
+  // Every publish leg answers with an object. A body that is not one is read
+  // as empty rather than crashing the caller on its first member read.
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : {};
+}
+
+/**
+ * GET a JSON document from the app server.
+ *
+ * Separate from `postJson` only because the payload may legitimately be an
+ * array: the comment list is one. The refusal handling is the same leg and
+ * the same rules, so it is shared rather than restated.
+ */
+export async function getJson(
+  deps: PublishDeps,
+  url: string
+): Promise<unknown> {
+  let response: Response;
+  try {
+    response = await deps.fetch(url);
+  } catch (error) {
+    throw new PublishError(
+      'service_unreachable',
+      `could not reach ${url}: ${(error as Error).message}`
+    );
+  }
+  return readJson(response);
+}
+
+/**
+ * Throw the app server's refusal, or hand back whatever it answered with.
+ *
+ * The shape is deliberately `unknown`: the grant legs answer with an object
+ * and the comment list answers with an array, so narrowing belongs to the
+ * caller that knows which it asked for.
+ */
+async function readJson(response: Response): Promise<unknown> {
+  const parsed = await response.json().catch(() => undefined);
 
   if (!response.ok) {
     // Clients key on `code`, never on prose. RFC 9457 says so about its own
-    // `detail` member: consumers should not parse it for information.
+    // `detail` member: consumers should not parse it for information. A body
+    // that is not a problem document still has to produce a refusal, so an
+    // unusable one degrades to `unknown` rather than throwing here.
+    const problem =
+      typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : {};
     throw new ServerRefusal(
-      String(parsed['code'] ?? 'unknown'),
+      String(problem['code'] ?? 'unknown'),
       response.status,
-      parsed
+      problem
     );
   }