relic-mcp 0.2.0 → 0.3.0

package/src/server.ts

@@ -38,6 +38,7 @@ import {
   publish,
   ServerRefusal,
 } from './publish.ts';
+import { republish } from './republish.ts';
 
 export {
   LEGACY_PROTOCOL_VERSIONS,
@@ -73,6 +74,26 @@ export const TOOL_NAME = 'relic_publish';
  */
 export const DESCRIBE_TOOL_NAME = 'relic_describe_client';
 
+/**
+ * The republish tool: a new version of a relic this machine published.
+ *
+ * A separate tool rather than an argument on publish, because the two calls
+ * hold different secrets and different failure modes. Publish mints an id
+ * and a key; republish consumes ones recorded locally, and refusing when
+ * they are absent is the machine boundary made visible. Folding it into
+ * publish would turn "published from another machine" into a retry loop
+ * that can never succeed.
+ */
+export const REPUBLISH_TOOL_NAME = 'relic_republish';
+
+/**
+ * The ceiling on a publisher-supplied lifetime, matching the grant
+ * contract's `maxTtlDays`. Refusing here keeps a typo like 36500 from
+ * encrypting the file and round-tripping a grant only to be turned down
+ * after the work is done.
+ */
+const MAX_TTL_DAYS = 3650;
+
 export const TOOL_DEFINITION = {
   name: TOOL_NAME,
   title: 'Publish a relic',
@@ -93,6 +114,15 @@ export const TOOL_DEFINITION = {
           'Optional. Overrides the name written into the encrypted envelope ' +
           'header. Defaults to the basename of `path`.',
       },
+      ttl_days: {
+        type: 'integer',
+        minimum: 1,
+        maximum: MAX_TTL_DAYS,
+        description:
+          'Optional. Gives the relic a lifetime in days. Omit it and the ' +
+          'relic is kept until it is deleted. Shorter is better for ' +
+          'sensitive content.',
+      },
     },
     required: ['path'],
     additionalProperties: false,
@@ -102,7 +132,12 @@ export const TOOL_DEFINITION = {
     properties: {
       url: { type: 'string' },
       relic_id: { type: 'string' },
-      relic_expires_at: { type: 'string' },
+      version: {
+        type: 'integer',
+        minimum: 1,
+        description: 'Always 1 from this tool; republish counts upward.',
+      },
+      relic_expires_at: { type: ['string', 'null'] },
       renderer_class: { type: 'string' },
       filename: { type: 'string' },
       resolved_path: { type: 'string' },
@@ -112,6 +147,76 @@ export const TOOL_DEFINITION = {
     required: [
       'url',
       'relic_id',
+      'version',
+      'relic_expires_at',
+      'renderer_class',
+      'filename',
+      'resolved_path',
+      'report_url',
+      'disclosure_url',
+    ],
+    additionalProperties: false,
+  },
+} as const;
+
+export const 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.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      relic_id: {
+        type: 'string',
+        description: 'The 26-character relic id the original publish returned.',
+      },
+      path: {
+        type: 'string',
+        description:
+          'Filesystem path to the file that becomes the new version.',
+      },
+      filename: {
+        type: 'string',
+        description:
+          'Optional. Overrides the name written into the encrypted envelope ' +
+          'header of the new version. Defaults to the basename of `path`.',
+      },
+      ttl_days: {
+        type: 'integer',
+        minimum: 1,
+        maximum: MAX_TTL_DAYS,
+        description:
+          'Optional. A lifetime in days, forwarded on the republish ' +
+          "request. The service fixes a relic's lifetime at its first " +
+          'publish, so treat this as reserved.',
+      },
+    },
+    required: ['relic_id', 'path'],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      relic_id: { type: 'string' },
+      version: {
+        type: 'integer',
+        minimum: 2,
+        description: 'The version just published.',
+      },
+      relic_expires_at: { type: ['string', 'null'] },
+      renderer_class: { type: 'string' },
+      filename: { type: 'string' },
+      resolved_path: { type: 'string' },
+      report_url: { type: 'string' },
+      disclosure_url: { type: 'string' },
+    },
+    required: [
+      'relic_id',
+      'version',
       'relic_expires_at',
       'renderer_class',
       'filename',
@@ -137,10 +242,22 @@ export const DESCRIBE_TOOL_DEFINITION = {
   },
 } as const;
 
+/**
+ * The build stamps the published version in, from package.json, which the
+ * release workflow rewrites before it builds. It used to be a literal, and it
+ * went stale immediately: the tarball published as 0.2.0 introduced itself to
+ * every client as 0.1.0.
+ *
+ * An unbuilt run says so rather than guessing at a release number, because a
+ * dev process claiming a version somebody could look up is worse than one
+ * admitting it has none.
+ */
+export const SERVER_VERSION = process.env.RELIC_MCP_VERSION ?? '0.0.0-dev';
+
 export const SERVER_INFO = {
   name: 'relic',
   title: 'Relic',
-  version: '0.1.0',
+  version: SERVER_VERSION,
 } as const;
 
 export const CAPABILITIES = { tools: {} } as const;
@@ -206,7 +323,13 @@ export async function handleMessage(
       return {
         jsonrpc: '2.0',
         id,
-        result: { tools: [TOOL_DEFINITION, DESCRIBE_TOOL_DEFINITION] },
+        result: {
+          tools: [
+            TOOL_DEFINITION,
+            REPUBLISH_TOOL_DEFINITION,
+            DESCRIBE_TOOL_DEFINITION,
+          ],
+        },
       };
 
     case 'tools/call':
@@ -221,6 +344,26 @@ export async function handleMessage(
   }
 }
 
+/**
+ * What a publisher of executable content needs to know, and nobody else can
+ * use.
+ *
+ * `html` and `jsx` are the two classes that render author-written code, and
+ * that code now runs in a frame served a policy with no remote source, so a
+ * page built against a CDN comes out bare. The recipient cannot fix that; the
+ * person publishing can, by inlining what the page needs.
+ *
+ * Every other class is inert markup or bytes, so the note would be noise.
+ */
+function isolationNote(rendererClass: string): string {
+  if (rendererClass !== 'html' && rendererClass !== 'jsx') return '';
+  return (
+    'It renders in an isolated frame with no network access, so external ' +
+    'images, fonts, scripts, and fetches will not load. Inline whatever the ' +
+    'page needs.\n'
+  );
+}
+
 async function callTool(
   id: string | number | null,
   params: Record<string, unknown>,
@@ -238,6 +381,9 @@ async function callTool(
           key_transmitted_to_service: false,
           plaintext_transmitted_to_service: false,
           ciphertext_destination: 'object storage, via a signed URL',
+          local_publish_state:
+            'relic id, key, and publish token per relic, written 0600 under ' +
+            'the user config directory; never printed, never sent',
           service_origin: deps.serviceOrigin,
         },
         isError: false,
@@ -245,6 +391,10 @@ async function callTool(
     };
   }
 
+  if (params['name'] === REPUBLISH_TOOL_NAME) {
+    return callRepublish(id, params, deps);
+  }
+
   if (params['name'] !== TOOL_NAME) {
     return errorResponse(
       id,
@@ -266,8 +416,21 @@ async function callTool(
   const filename =
     typeof args['filename'] === 'string' ? args['filename'] : undefined;
 
+  const ttlDays = parseTtlDays(args['ttl_days']);
+  if (!ttlDays.ok) {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      `\`ttl_days\` must be an integer between 1 and ${MAX_TTL_DAYS}, or ` +
+        'omitted to keep the relic until it is deleted'
+    );
+  }
+
   try {
-    const result = await publish({ path, filename }, deps);
+    const result = await publish(
+      { path, filename, ttl_days: ttlDays.days },
+      deps
+    );
     return {
       jsonrpc: '2.0',
       id,
@@ -280,10 +443,22 @@ async function callTool(
           {
             type: 'text',
             text:
-              `Published ${result.filename} as a relic.\n\n${result.url}\n\n` +
-              `Expires ${result.relic_expires_at}. Anyone with this link, ` +
+              `Published ${result.filename} as version 1 of a new relic.\n\n` +
+              `${result.url}\n\n` +
+              // No lifetime is the default, so the agent relaying this needs
+              // a sentence that says so, not a date-shaped hole.
+              (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.\n' +
+              'fragment and it is now in this transcript. This machine can ' +
+              'republish it later; the link will not change.\n' +
+              // The publisher is the only party who can act on this, and the
+              // publish call is the only moment they are looking. The relic
+              // page used to carry it to the recipient, who cannot do
+              // anything about a font that will not load.
+              isolationNote(result.renderer_class) +
               `What Relic knows: ${result.disclosure_url}`,
           },
         ],
@@ -296,6 +471,122 @@ async function callTool(
   }
 }
 
+async function callRepublish(
+  id: string | number | null,
+  params: Record<string, unknown>,
+  deps: PublishDeps
+): Promise<JsonRpcResponse> {
+  const args = (params['arguments'] ?? {}) as Record<string, unknown>;
+  const relicId = args['relic_id'];
+  if (typeof relicId !== 'string' || relicId.length === 0) {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      '`relic_id` is required and must be a string'
+    );
+  }
+
+  const path = args['path'];
+  if (typeof path !== 'string' || path.length === 0) {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      '`path` is required and must be a string'
+    );
+  }
+
+  const filename =
+    typeof args['filename'] === 'string' ? args['filename'] : undefined;
+
+  const ttlDays = parseTtlDays(args['ttl_days']);
+  if (!ttlDays.ok) {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      `\`ttl_days\` must be an integer between 1 and ${MAX_TTL_DAYS}, or ` +
+        'omitted to leave the lifetime as the first publish set it'
+    );
+  }
+
+  try {
+    const result = await republish(
+      { relic_id: relicId, path, filename, ttl_days: ttlDays.days },
+      deps
+    );
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        // No URL is printed here, on purpose. It has not changed, and
+        // reprinting it would reprint the key for no new reader; the first
+        // publish already made that disclosure once.
+        content: [
+          {
+            type: 'text',
+            text:
+              `Republished ${result.filename} as version ${result.version} ` +
+              `of relic ${result.relic_id}.\n\n` +
+              'The share URL is unchanged: everyone holding the existing ' +
+              'link, including its fragment, now sees this content. There ' +
+              'is no new link to hand out.\n\n' +
+              (result.relic_expires_at === null
+                ? 'The relic does not expire; it is kept until it is deleted.'
+                : `Expires ${result.relic_expires_at}.`) +
+              '\n' +
+              `What Relic knows: ${result.disclosure_url}`,
+          },
+        ],
+        structuredContent: result,
+        isError: false,
+      },
+    };
+  } catch (error) {
+    return { jsonrpc: '2.0', id, result: toolError(error) };
+  }
+}
+
+/**
+ * A lifetime is opt-in: absent or null means no change from the default. A
+ * value that fails the contract is refused rather than dropped, because
+ * silently dropping it does the opposite of what was asked: a relic meant
+ * to die in days lives forever.
+ */
+function parseTtlDays(
+  raw: unknown
+): { ok: true; days: number | undefined } | { ok: false } {
+  if (raw === undefined || raw === null) return { ok: true, days: undefined };
+  if (
+    typeof raw !== 'number' ||
+    !Number.isSafeInteger(raw) ||
+    raw < 1 ||
+    raw > MAX_TTL_DAYS
+  ) {
+    return { ok: false };
+  }
+  return { ok: true, days: raw };
+}
+
+/**
+ * Republish refusals a publisher must understand on their own terms.
+ *
+ * The server's problem document carries the code; these sentences carry
+ * what the publisher can still do, because "403" and "410" answer nothing
+ * a human would ask. The two must stay distinct: one means this machine
+ * lost its standing, the other means nobody has any, ever again.
+ */
+const REFUSAL_GUIDANCE: Readonly<Record<string, string>> = {
+  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.',
+};
+
 /**
  * A failed publish is a tool error, not a protocol error.
  *
@@ -313,8 +604,16 @@ function toolError(error: unknown): Record<string, unknown> {
     };
   }
   if (error instanceof ServerRefusal) {
+    const guidance = REFUSAL_GUIDANCE[error.code];
     return {
-      content: [{ type: 'text', text: `${error.code}: ${error.message}` }],
+      content: [
+        {
+          type: 'text',
+          text:
+            `${error.code}: ${error.message}` +
+            (guidance === undefined ? '' : `\n${guidance}`),
+        },
+      ],
       structuredContent: { code: error.code, ...error.problem },
       isError: true,
     };
@@ -356,6 +655,14 @@ What the service operator can see: that a relic exists, roughly how big it is,
 what coarse class it was declared as, the publishing IP, and when it was
 fetched. Never the contents, and never the key.
 
+What this keeps on disk: for each relic you publish, its id, its key, and a
+publish token, in a 0600 file under your user config directory. That record
+is what lets a relic be republished later, and it is why republishing works
+only on the machine that published. The token's SHA-256 is the only copy the
+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 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/src/state.ts

@@ -0,0 +1,185 @@
+/**
+ * Durable publish state: what a later republish needs.
+ *
+ * A republish has to encrypt under the SAME key as version 1, or the share
+ * URL stops decrypting anything, and it has to present the publish token the
+ * first grant handed out, or the service refuses it. Neither exists anywhere
+ * but this machine: the service holds a hash of the token and nothing of the
+ * key. So losing this file means those relics can never be updated from
+ * here, which makes it state a human cannot repair by hand elsewhere. It is
+ * written before a publish reports success and read at the point of use,
+ * never cached in a process global.
+ *
+ * The file holds secrets. It is created 0600 inside a 0700 directory under
+ * the user's config directory, and nothing in this module ever puts the key
+ * or the token into a message, a log line, or an error.
+ */
+
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** What this machine remembers about one published relic. */
+export interface PublishState {
+  /** The version-1 content key, base64url, exactly as it rides the URL fragment. */
+  readonly key: string;
+  /**
+   * The bearer secret authorizing a republish. The service stores only its
+   * SHA-256, so this copy is the only usable one in existence.
+   */
+  readonly publish_token: string;
+  /** How many versions this machine has published; 1 after the first. */
+  readonly version: number;
+}
+
+interface StateFile {
+  readonly relics: Record<string, PublishState>;
+}
+
+/**
+ * Where the state lives.
+ *
+ * Behind one helper, redirected with `RELIC_PUBLISH_STATE`, so tests point it
+ * at a scratch path and a user with an unusual setup can move it. The default
+ * is the user's config directory rather than the repo or the cwd, because the
+ * publisher's identity here is the machine and user who ran the publish, not
+ * whatever directory the server happened to start in.
+ */
+export function publishStatePath(): string {
+  const override = process.env['RELIC_PUBLISH_STATE'];
+  if (override !== undefined && override.length > 0) return override;
+
+  const configRoot =
+    process.env['XDG_CONFIG_HOME'] !== undefined &&
+    process.env['XDG_CONFIG_HOME'].length > 0
+      ? process.env['XDG_CONFIG_HOME']
+      : join(homedir(), '.config');
+  return join(configRoot, 'relic-mcp', 'publish-state.json');
+}
+
+/**
+ * Writers queue behind one chain, so two publishes finishing close together
+ * cannot read-modify-write past each other and silently drop one relic's
+ * entry. Losing an entry to a race would orphan that relic with no error
+ * anywhere, which is the quietest possible way to lose republish rights.
+ */
+let writeChain: Promise<void> = Promise.resolve();
+
+/** Load one relic's state, or undefined when this machine never published it. */
+export async function loadPublishState(
+  relicId: string
+): Promise<PublishState | undefined> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(publishStatePath(), 'utf8'));
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return undefined;
+    if (error instanceof SyntaxError) {
+      // The message names the file and stops. Echoing any of the bytes would
+      // put secrets into an error path, and a truncated tail of JSON is where
+      // a key or token is most likely to sit in one piece.
+      throw new Error(
+        `publish state at ${publishStatePath()} is not valid JSON. It cannot ` +
+          'be read, so relics recorded in it cannot be republished from this ' +
+          'machine until it is fixed or removed.'
+      );
+    }
+    throw new Error(
+      `could not read publish state at ${publishStatePath()}: ${code}`
+    );
+  }
+
+  const entry = (parsed as StateFile | null)?.relics?.[relicId];
+  if (entry === undefined) return undefined;
+  if (
+    typeof entry !== 'object' ||
+    typeof entry.key !== 'string' ||
+    typeof entry.publish_token !== 'string' ||
+    typeof entry.version !== 'number' ||
+    !Number.isSafeInteger(entry.version) ||
+    entry.version < 1
+  ) {
+    throw new Error(
+      `publish state at ${publishStatePath()} holds a malformed entry for ` +
+        'this relic id.'
+    );
+  }
+  return entry;
+}
+
+/**
+ * Record or update one relic's state, preserving every other entry.
+ *
+ * Called only after the service has accepted the object, so the file never
+ * promises a republish the service does not know about.
+ */
+export async function savePublishState(
+  relicId: string,
+  state: PublishState
+): Promise<void> {
+  const run = writeChain.then(() => writeEntry(relicId, state));
+  // A failed write must not poison the chain for later ones; it is observed
+  // here and rethrown for the caller, who has not yet reported success.
+  writeChain = run.catch(() => undefined);
+  await run;
+}
+
+async function writeEntry(relicId: string, state: PublishState): Promise<void> {
+  const path = publishStatePath();
+  const dir = dirname(path);
+
+  // 0700 applies to the directories this creates, not to a config root that
+  // already exists: chmod-ing ~/.config itself would break other tools.
+  await mkdir(dir, { mode: 0o700, recursive: true });
+
+  const existing = await readWholeFile(path);
+  const relics = { ...existing?.relics, [relicId]: state };
+
+  // Written to a sibling then renamed over, so a crash mid-write leaves the
+  // previous intact file rather than half of the new one. A torn file would
+  // take every relic's republish rights with it, not just the one in flight.
+  const temp = `${path}.tmp`;
+  await writeFile(temp, `${JSON.stringify({ relics }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await rename(temp, path);
+}
+
+async function readWholeFile(path: string): Promise<StateFile | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return undefined;
+    throw new Error(`could not read publish state at ${path}: ${code}`);
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as StateFile | null;
+    if (parsed === null || typeof parsed !== 'object') {
+      throw new Error('not an object');
+    }
+    return parsed;
+  } catch {
+    throw new Error(
+      `publish state at ${path} is not valid JSON. It cannot be updated, so ` +
+        'this publish cannot be recorded and this relic cannot later be ' +
+        'republished from this machine until the file is fixed or removed.'
+    );
+  }
+}
+
+/** Exposed for tests asserting the on-disk permissions, nothing else. */
+export async function publishStateModes(): Promise<{
+  file: number;
+  directory: number;
+}> {
+  const path = publishStatePath();
+  const [file, directory] = await Promise.all([
+    stat(path),
+    stat(dirname(path)),
+  ]);
+  return { file: file.mode & 0o777, directory: directory.mode & 0o777 };
+}