relic-mcp 0.2.0 → 0.3.1

package/dist/relic-mcp.js

@@ -190,6 +190,24 @@ function encodeKey(key) {
   }
   return out;
 }
+function decodeKey(encoded) {
+  const bytes = [];
+  let accumulator = 0;
+  let bitsHeld = 0;
+  for (const ch of encoded) {
+    const index = B64URL.indexOf(ch);
+    if (index < 0) {
+      throw new MalformedFragmentError(`key contains ${JSON.stringify(ch)}, outside base64url`);
+    }
+    accumulator = accumulator << 6 | index;
+    bitsHeld += 6;
+    if (bitsHeld >= 8) {
+      bitsHeld -= 8;
+      bytes.push(accumulator >>> bitsHeld & 255);
+    }
+  }
+  return new Uint8Array(bytes);
+}
 function generateKey() {
   const key = new Uint8Array(KEY_BYTES);
   crypto.getRandomValues(key);
@@ -329,6 +347,7 @@ function concat(parts) {
 // ../relic-format/src/id.ts
 var ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
 var ID_ENTROPY_BYTES = 16;
+var ID_LENGTH = 26;
 var RESERVED_SEGMENTS = [
   "abuse",
   "policy",
@@ -341,7 +360,8 @@ var RESERVED_SEGMENTS = [
   "api",
   "health",
   ".well-known",
-  "sandbox.html"
+  "sandbox.html",
+  "install"
 ];
 var RESERVED_NORMALIZED = new Set(RESERVED_SEGMENTS.map((word) => foldAliases(word.toLowerCase())));
 
@@ -365,6 +385,32 @@ function foldAliases(lowered) {
   }
   return out;
 }
+function normalizeRelicId(candidate) {
+  return foldAliases(candidate.toLowerCase());
+}
+function parseRelicId(candidate) {
+  if (candidate.length !== ID_LENGTH) {
+    throw new InvalidRelicIdError("length", `relic id must be ${ID_LENGTH} characters, got ${candidate.length}`);
+  }
+  const normalized = normalizeRelicId(candidate);
+  for (const ch of normalized) {
+    if (!ALPHABET.includes(ch)) {
+      throw new InvalidRelicIdError("alphabet", `relic id contains ${JSON.stringify(ch)}, outside Crockford base32`);
+    }
+  }
+  if (RESERVED_NORMALIZED.has(normalized)) {
+    throw new InvalidRelicIdError("reserved", `relic id normalizes onto the reserved segment ${normalized}`);
+  }
+  return normalized;
+}
+function isValidRelicId(candidate) {
+  try {
+    parseRelicId(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function encodeRelicId(entropy) {
   if (entropy.length !== ID_ENTROPY_BYTES) {
     throw new InvalidRelicIdError("length", `relic id entropy must be ${ID_ENTROPY_BYTES} bytes`);
@@ -446,9 +492,9 @@ var EXTENSIONS = {
   "7z": "archive",
   rar: "archive",
   ts: "code",
-  tsx: "code",
   js: "code",
-  jsx: "code",
+  jsx: "jsx",
+  tsx: "jsx",
   mjs: "code",
   cjs: "code",
   json: "code",
@@ -540,7 +586,40 @@ function looksTextual(content) {
   }
   return suspicious / limit < 0.01;
 }
-var HTML_PREFIXES = ["<!doctype html", "<html", "<!-- ", "<svg"];
+var HTML_PREFIXES = [
+  "<!doctype",
+  "<?xml",
+  "<html",
+  "<head",
+  "<body",
+  "<meta",
+  "<title",
+  "<link",
+  "<style",
+  "<script",
+  "<svg",
+  "<div",
+  "<main",
+  "<section",
+  "<article",
+  "<header",
+  "<footer",
+  "<nav",
+  "<aside",
+  "<table",
+  "<form",
+  "<ul",
+  "<ol",
+  "<dl",
+  "<h1",
+  "<h2",
+  "<h3",
+  "<h4",
+  "<h5",
+  "<h6",
+  "<p>",
+  "<!--"
+];
 function deriveRendererClass(content, filename) {
   if (content.length === 0)
     return "binary";
@@ -562,6 +641,80 @@ function deriveRendererClass(content, filename) {
   }
   return "binary";
 }
+// src/state.ts
+import { mkdir, readFile as readFile2, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+function publishStatePath() {
+  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");
+}
+var writeChain = Promise.resolve();
+async function loadPublishState(relicId) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile2(publishStatePath(), "utf8"));
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT")
+      return;
+    if (error instanceof SyntaxError) {
+      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?.relics?.[relicId];
+  if (entry === undefined)
+    return;
+  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;
+}
+async function savePublishState(relicId, state) {
+  const run = writeChain.then(() => writeEntry(relicId, state));
+  writeChain = run.catch(() => {
+    return;
+  });
+  await run;
+}
+async function writeEntry(relicId, state) {
+  const path = publishStatePath();
+  const dir = dirname(path);
+  await mkdir(dir, { mode: 448, recursive: true });
+  const existing = await readWholeFile(path);
+  const relics = { ...existing?.relics, [relicId]: state };
+  const temp = `${path}.tmp`;
+  await writeFile(temp, `${JSON.stringify({ relics }, null, 2)}
+`, {
+    mode: 384
+  });
+  await rename(temp, path);
+}
+async function readWholeFile(path) {
+  let raw;
+  try {
+    raw = await readFile2(path, "utf8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT")
+      return;
+    throw new Error(`could not read publish state at ${path}: ${code}`);
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    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.");
+  }
+}
+
 // src/publish.ts
 class PublishError extends Error {
   code;
@@ -619,7 +772,8 @@ async function publish(input, deps) {
         renderer_class: rendererClass,
         publishing_client: deps.clientName,
         declared_size_bytes: source.bytes.length,
-        declared_ciphertext_bytes: container2.length
+        declared_ciphertext_bytes: container2.length,
+        ...input.ttl_days === undefined ? {} : { ttl_days: input.ttl_days }
       });
     } catch (error) {
       if (error instanceof ServerRefusal && error.code === "relic_id_collision") {
@@ -628,21 +782,27 @@ async function publish(input, deps) {
       }
       throw error;
     }
-    const upload = await deps.fetch(String(grant["upload_url"]), {
-      method: "PUT",
-      headers: { "content-length": String(container2.length) },
-      body: container2
-    });
-    if (!upload.ok) {
-      throw new PublishError("upload_failed", `upload returned ${upload.status}`, { relic_id: relicId, status: upload.status });
+    const publishToken = grant["publish_token"];
+    if (typeof publishToken !== "string" || publishToken.length === 0) {
+      throw new PublishError("grant_missing_publish_token", "the grant carried no publish_token, so the relic would never be " + "republishable from this machine", { relic_id: relicId });
     }
+    await putContainer(deps, relicId, String(grant["upload_url"]), container2);
+    await reportComplete(deps, relicId);
+    const url = relicUrl(deps.relicOrigin, relicId, key);
     try {
-      await postJson(deps, `${deps.serviceOrigin}/api/relics/${relicId}/complete`, {});
-    } catch {}
+      await savePublishState(relicId, {
+        key: encodeKey(key),
+        publish_token: publishToken,
+        version: 1
+      });
+    } catch (error) {
+      throw new PublishError("local_state_write_failed", "the relic is published and the link works, but recording it for " + `later republishing failed, so it cannot be republished from this ` + `machine: ${error.message}`, { relic_id: relicId, url });
+    }
     return {
-      url: relicUrl(deps.relicOrigin, relicId, key),
+      url,
       relic_id: relicId,
-      relic_expires_at: String(grant["relic_expires_at"]),
+      version: 1,
+      relic_expires_at: grant["relic_expires_at"] == null ? null : String(grant["relic_expires_at"]),
       renderer_class: rendererClass,
       filename,
       resolved_path: source.resolvedPath,
@@ -654,11 +814,11 @@ async function publish(input, deps) {
 }
 async function readSource(path, files) {
   const resolvedPath = files.resolve(path);
-  const stat = await files.stat(resolvedPath);
-  if (stat.kind === "directory") {
+  const stat2 = await files.stat(resolvedPath);
+  if (stat2.kind === "directory") {
     throw new PublishError("source_is_directory", `${resolvedPath} is a directory. Create an archive yourself and ` + "publish that, so the download-only outcome is yours to choose.");
   }
-  if (stat.kind === "other") {
+  if (stat2.kind === "other") {
     throw new PublishError("source_not_regular_file", `${resolvedPath} is not a regular file`);
   }
   let bytes;
@@ -686,6 +846,24 @@ async function postJson(deps, url, body) {
   }
   return parsed;
 }
+async function putContainer(deps, relicId, uploadUrl, container2) {
+  const upload = await deps.fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "content-length": String(container2.length) },
+    body: container2
+  });
+  if (!upload.ok) {
+    throw new PublishError("upload_failed", `upload returned ${upload.status}`, {
+      relic_id: relicId,
+      status: upload.status
+    });
+  }
+}
+async function reportComplete(deps, relicId) {
+  try {
+    await postJson(deps, `${deps.serviceOrigin}/api/relics/${relicId}/complete`, {});
+  } catch {}
+}
 var MIMETYPES = {
   md: "text/markdown",
   markdown: "text/markdown",
@@ -708,12 +886,15 @@ var MIMETYPES = {
   ogg: "audio/ogg",
   zip: "application/zip",
   gz: "application/gzip",
-  pdf: "application/pdf"
+  pdf: "application/pdf",
+  jsx: "text/jsx",
+  tsx: "text/tsx"
 };
 var CLASS_FALLBACK = {
   markdown: "text/markdown",
   code: "text/plain",
   html: "text/html",
+  jsx: "text/jsx",
   image: "application/octet-stream",
   media: "application/octet-stream",
   archive: "application/octet-stream",
@@ -730,9 +911,64 @@ function guessMimetype(filename, rendererClass) {
   return CLASS_FALLBACK[rendererClass];
 }
 
+// src/republish.ts
+async function republish(input, deps) {
+  if (!isValidRelicId(input.relic_id)) {
+    throw new PublishError("no_local_publish_state", `"${input.relic_id}" is not a relic id. Republish takes the ` + "26-character id the original publish returned.");
+  }
+  let state;
+  try {
+    const loaded = await loadPublishState(input.relic_id);
+    if (loaded === undefined) {
+      throw new PublishError("no_local_publish_state", `relic ${input.relic_id} was published from another machine and ` + "cannot be republished here. The key and the publish token live " + "only on the machine that made the first publish, and neither can " + "be reconstructed from the link or from the service. Publish the " + "content as a new relic instead.");
+    }
+    state = loaded;
+  } catch (error) {
+    if (error instanceof PublishError)
+      throw error;
+    throw new PublishError("local_state_unreadable", error.message);
+  }
+  const source = await readSource(input.path, deps.files);
+  const filename = input.filename ?? source.basename;
+  const rendererClass = deriveRendererClass(source.bytes, filename);
+  const container2 = await encryptRelic({
+    content: source.bytes,
+    filename,
+    mimetype: guessMimetype(filename, rendererClass),
+    key: decodeKey(state.key)
+  });
+  const grant = await postJson(deps, `${deps.serviceOrigin}/api/relics/${input.relic_id}/republish`, {
+    publish_token: state.publish_token,
+    renderer_class: rendererClass,
+    declared_size_bytes: source.bytes.length,
+    declared_ciphertext_bytes: container2.length,
+    ...input.ttl_days === undefined ? {} : { ttl_days: input.ttl_days }
+  });
+  await putContainer(deps, input.relic_id, String(grant["upload_url"]), container2);
+  await reportComplete(deps, input.relic_id);
+  const version = state.version + 1;
+  try {
+    await savePublishState(input.relic_id, { ...state, version });
+  } catch (error) {
+    throw new PublishError("local_state_write_failed", "the new version is live at the existing link, but updating the " + "local record failed, so the next republish from this machine may " + `report a stale version number: ${error.message}`, { relic_id: input.relic_id, version });
+  }
+  return {
+    relic_id: input.relic_id,
+    version,
+    relic_expires_at: grant["relic_expires_at"] == null ? null : String(grant["relic_expires_at"]),
+    renderer_class: rendererClass,
+    filename,
+    resolved_path: source.resolvedPath,
+    report_url: String(grant["report_url"]),
+    disclosure_url: String(grant["disclosure_url"])
+  };
+}
+
 // src/server.ts
 var TOOL_NAME = "relic_publish";
 var DESCRIBE_TOOL_NAME = "relic_describe_client";
+var REPUBLISH_TOOL_NAME = "relic_republish";
+var MAX_TTL_DAYS = 3650;
 var TOOL_DEFINITION = {
   name: TOOL_NAME,
   title: "Publish a relic",
@@ -747,6 +983,12 @@ var TOOL_DEFINITION = {
       filename: {
         type: "string",
         description: "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"],
@@ -757,7 +999,12 @@ var 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" },
@@ -767,6 +1014,65 @@ var TOOL_DEFINITION = {
     required: [
       "url",
       "relic_id",
+      "version",
+      "relic_expires_at",
+      "renderer_class",
+      "filename",
+      "resolved_path",
+      "report_url",
+      "disclosure_url"
+    ],
+    additionalProperties: false
+  }
+};
+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.",
+  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",
@@ -787,12 +1093,21 @@ var DESCRIBE_TOOL_DEFINITION = {
     additionalProperties: false
   }
 };
+var SERVER_VERSION = "0.3.1";
 var SERVER_INFO = {
   name: "relic",
   title: "Relic",
-  version: "0.1.0"
+  version: SERVER_VERSION
 };
 var CAPABILITIES = { tools: {} };
+var INSTRUCTIONS = `Relic turns a file on this machine into an encrypted link. Encryption happens locally, only ciphertext is uploaded, and the key lives in the URL fragment, which browsers never send to a server.
+
+Four 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. 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.
+4. 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.`;
 async function handleMessage(message, deps) {
   if (message.id === undefined)
     return;
@@ -810,7 +1125,8 @@ async function handleMessage(message, deps) {
         result: {
           protocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
           capabilities: CAPABILITIES,
-          serverInfo: SERVER_INFO
+          serverInfo: SERVER_INFO,
+          instructions: INSTRUCTIONS
         }
       };
     case "initialize": {
@@ -821,7 +1137,8 @@ async function handleMessage(message, deps) {
         result: {
           protocolVersion: isSupportedVersion(asked) ? asked : PROTOCOL_VERSION,
           capabilities: CAPABILITIES,
-          serverInfo: SERVER_INFO
+          serverInfo: SERVER_INFO,
+          instructions: INSTRUCTIONS
         }
       };
     }
@@ -831,7 +1148,13 @@ async function handleMessage(message, deps) {
       return {
         jsonrpc: "2.0",
         id: id2,
-        result: { tools: [TOOL_DEFINITION, DESCRIBE_TOOL_DEFINITION] }
+        result: {
+          tools: [
+            TOOL_DEFINITION,
+            REPUBLISH_TOOL_DEFINITION,
+            DESCRIBE_TOOL_DEFINITION
+          ]
+        }
       };
     case "tools/call":
       return callTool(id2, message.params ?? {}, deps);
@@ -839,6 +1162,12 @@ async function handleMessage(message, deps) {
       return errorResponse(id2, ERROR_CODES.methodNotFound, `unknown method: ${message.method}`);
   }
 }
+function isolationNote(rendererClass) {
+  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.
+`;
+}
 async function callTool(id2, params, deps) {
   if (params["name"] === DESCRIBE_TOOL_NAME) {
     return {
@@ -852,12 +1181,16 @@ async function callTool(id2, params, deps) {
           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
       }
     };
   }
+  if (params["name"] === REPUBLISH_TOOL_NAME) {
+    return callRepublish(id2, params, deps);
+  }
   if (params["name"] !== TOOL_NAME) {
     return errorResponse(id2, ERROR_CODES.invalidParams, `unknown tool: ${String(params["name"])}`);
   }
@@ -867,8 +1200,12 @@ async function callTool(id2, params, deps) {
     return errorResponse(id2, 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(id2, 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: id2,
@@ -876,11 +1213,51 @@ async function callTool(id2, params, deps) {
         content: [
           {
             type: "text",
-            text: `Published ${result.filename} as a relic.
+            text: `Published ${result.filename} as version 1 of a new relic.
 
-${result.url}
+` + `${result.url}
 
-` + `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.
+` + (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}`
+          }
+        ],
+        structuredContent: result,
+        isError: false
+      }
+    };
+  } catch (error) {
+    return { jsonrpc: "2.0", id: id2, result: toolError(error) };
+  }
+}
+async function callRepublish(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 path = args["path"];
+  if (typeof path !== "string" || path.length === 0) {
+    return errorResponse(id2, 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(id2, 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: id2,
+      result: {
+        content: [
+          {
+            type: "text",
+            text: `Republished ${result.filename} as version ${result.version} ` + `of relic ${result.relic_id}.
+
+` + "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.
+
+` + (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}`
           }
         ],
@@ -892,6 +1269,18 @@ ${result.url}
     return { jsonrpc: "2.0", id: id2, result: toolError(error) };
   }
 }
+function parseTtlDays(raw) {
+  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 };
+}
+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."
+};
 function toolError(error) {
   if (error instanceof PublishError) {
     return {
@@ -901,8 +1290,15 @@ function toolError(error) {
     };
   }
   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 ? "" : `
+${guidance}`)
+        }
+      ],
       structuredContent: { code: error.code, ...error.problem },
       isError: true
     };
@@ -937,6 +1333,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
@@ -1044,9 +1448,9 @@ function createHttpHandler(deps, options = {}) {
 
 // src/installer.ts
 import { spawnSync } from "node:child_process";
-import { copyFile, mkdir, readFile as readFile2, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { copyFile, mkdir as mkdir2, readFile as readFile3, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/install.ts
@@ -1094,6 +1498,12 @@ var HARNESSES = [
     configPath: ".codex/config.toml"
   }
 ];
+var DEFAULT_SERVER_SPEC = {
+  name: "relic",
+  command: "npx",
+  args: ["-y", "relic-mcp@latest"],
+  env: {}
+};
 
 class UnknownHarnessError extends Error {
 }
@@ -1269,10 +1679,10 @@ function parseArgs(argv) {
   return options;
 }
 function packageRoot() {
-  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  return resolve(dirname2(fileURLToPath(import.meta.url)), "..");
 }
 async function exists(path) {
-  return readFile2(path).then(() => true).catch(() => false);
+  return readFile3(path).then(() => true).catch(() => false);
 }
 async function runInstall(argv) {
   let options;
@@ -1284,12 +1694,7 @@ async function runInstall(argv) {
 ${USAGE}`);
     process.exit(2);
   }
-  const spec = {
-    name: options.name,
-    command: "npx",
-    args: ["-y", "relic-mcp"],
-    env: {}
-  };
+  const spec = { ...DEFAULT_SERVER_SPEC, name: options.name };
   if (options.print && options.client === undefined) {
     process.stdout.write(snippetFor(withOrigin(spec, options)));
     return;
@@ -1303,15 +1708,15 @@ ${USAGE}`);
     await installClaudeCode(options);
     return;
   }
-  const home = homedir();
+  const home = homedir2();
   const harness = HARNESSES.find((h) => h.id === options.client);
   if (harness === undefined) {
     process.stderr.write(`Unknown client ${options.client}. Known: ` + `${HARNESSES.map((h) => h.id).join(", ")}
 `);
     process.exit(2);
   }
-  const path = join(home, harness.configPath);
-  const existing = await readFile2(path, "utf8").catch(() => {
+  const path = join2(home, harness.configPath);
+  const existing = await readFile3(path, "utf8").catch(() => {
     return;
   });
   let plan;
@@ -1339,8 +1744,8 @@ ${USAGE}`);
   if (existing !== undefined) {
     await copyFile(path, `${path}.relic-backup`);
   }
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, plan.contents);
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, plan.contents);
   process.stdout.write(`${plan.replaced ? "Replaced" : "Added"} "${resolved.name}" in ${path}
 ` + (existing === undefined ? "" : `Previous config saved to ${path}.relic-backup
 `) + `Restart ${harness.label} to pick it up.
@@ -1348,7 +1753,7 @@ ${USAGE}`);
 }
 async function installClaudeCode(options) {
   const root = packageRoot();
-  if (!await exists(join(root, ".claude-plugin", "marketplace.json"))) {
+  if (!await exists(join2(root, ".claude-plugin", "marketplace.json"))) {
     process.stderr.write("This copy of relic-mcp does not carry the plugin manifests, so it " + "cannot be installed as a Claude Code plugin. Use --print and add " + `the server manually, or install a newer version.
 `);
     process.exit(1);
@@ -1382,14 +1787,14 @@ function withOrigin(spec, options) {
   } catch (error) {
     process.stderr.write(`${error.message}
 
-Pass --origin https://your-relic-service
+Pass --origin https://relik.link
 `);
     process.exit(2);
   }
   return { ...spec, env: { RELIC_SERVICE_ORIGIN: origin } };
 }
 async function reportDetected() {
-  const home = homedir();
+  const home = homedir2();
   const lines = ["Harnesses detected here:", ""];
   for (const harness of HARNESSES) {
     if (harness.format === "plugin") {
@@ -1397,8 +1802,8 @@ async function reportDetected() {
       lines.push(`  ${found2.status === 0 ? "*" : " "} ${harness.id.padEnd(15)}${harness.label}`);
       continue;
     }
-    const dir = dirname(join(home, harness.configPath));
-    const found = await stat(dir).then((info) => info.isDirectory()).catch(() => false);
+    const dir = dirname2(join2(home, harness.configPath));
+    const found = await stat2(dir).then((info) => info.isDirectory()).catch(() => false);
     lines.push(`  ${found ? "*" : " "} ${harness.id.padEnd(15)}${harness.label}`);
   }
   lines.push("", "Install with:", "  relic-mcp install --client <id>", "");