relic-mcp 0.2.0 → 0.3.0

package/mcp-servers.json

@@ -2,10 +2,10 @@
   "relic": {
     "type": "stdio",
     "command": "npx",
-    "args": ["-y", "relic-mcp@0.1.1"],
+    "args": ["-y", "relic-mcp@0.2.0"],
     "env": {
-      "RELIC_SERVICE_ORIGIN": "https://relic-wh2jw5fg2q-uc.a.run.app",
-      "RELIC_CLIENT_NAME": "relic-plugin/0.1.0"
+      "RELIC_SERVICE_ORIGIN": "https://relik.link",
+      "RELIC_CLIENT_NAME": "relic-plugin/0.2.0"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relic-mcp",
-  "version": "0.2.0",
+  "version": "0.3.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",

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 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, what the recipient sees, how long a link lives, and what the service can and cannot read.
 ---
 
 # Relic
@@ -27,8 +27,41 @@ context and pass its text; pass where it lives.
 Optional arguments worth knowing:
 
 - `filename` overrides the display name shown to the recipient.
-- `ttl_days` shortens the life of the link. Shorter is better for anything
-  sensitive; the default is the service maximum.
+- `ttl_days` gives the link a lifetime in days, 1 to 3650. A relic is kept
+  until it is deleted unless you set one. Shorter is better for anything
+  sensitive: when the content should stop being available, say when.
+
+The result reports the relic as version 1 and its id. Keep the id if a later
+version of the same content will replace this one; that is what
+`relic_republish` is for.
+
+## Republishing
+
+Call `relic_republish` with the relic id and a new file:
+
+```
+relic_republish(relic_id: "0a2c...", path: "/Users/me/Downloads/report-v2.html")
+```
+
+The new file becomes version 2, then 3, and so on, encrypted under the same
+key as version 1. **The share URL does not change**: everyone holding the
+existing link now sees the new content, and there is no new link to hand out.
+`relic_id` is the 26-character id the original publish returned, not the URL.
+Optional `filename` overrides the display name in the new version.
+
+Two things to know before promising an update:
+
+- **Republishing works only on the machine that published.** The key and the
+  publish token are recorded locally when the first publish happens, in a
+  0600 file under the user's config directory. On any other machine the tool
+  refuses: the relic was published from another machine and cannot be
+  republished here. Neither secret is ever printed or logged.
+- **A takedown is terminal.** If the relic was removed, republishing cannot
+  revive it, ever, whatever token is presented. The tool says so plainly;
+  publish the content as a new relic instead.
+
+A relic's lifetime is set at its first publish and carries across versions
+unchanged.
 
 ## Say this when you hand over the link
 
@@ -44,7 +77,8 @@ all, it should not go through an agent.
 
 Also worth one line, unprompted, the first time in a session:
 
-- links expire (the tool returns the exact date)
+- a relic is kept until it is deleted, unless it was published with a
+  `ttl_days` lifetime, in which case the tool returns the exact date
 - opens are capped, and the tool's mint response reports how many remain
 - anyone with the link can read it; there are no per-recipient permissions
 
@@ -61,11 +95,11 @@ fails: chat clients and ticket systems sometimes cut fragments.
 
 ## When not to use it
 
-- **Something that belongs in the repo.** Commit it. A relic expires; a commit
-  does not.
-- **A client deliverable.** Those have a durable home, and a link that dies in
-  a week is not it. Publish a relic in addition if someone needs to look at it
-  now, never instead.
+- **Something that belongs in the repo.** Commit it. A relic is a link you
+  hand someone, not a place work lives; the repo is.
+- **A client deliverable.** Those have a durable home, and a share link is
+  not it, even one with no expiry. Publish a relic in addition if someone
+  needs to look at it now, never instead.
 - **Credentials, keys, or tokens.** Encrypted in transit and at rest still ends
   with a secret sitting in a URL in a transcript.
 

package/src/http.ts

@@ -2,9 +2,13 @@
  * Streamable HTTP transport, revision `2026-07-28`.
  *
  * Stateless by construction: a single POST endpoint, one HTTP request per
- * JSON-RPC message, no session, and no `Mcp-Session-Id`. Nothing is retained
- * between calls, so a load balancer can round-robin across processes with no
- * sticky routing and no shared session store.
+ * JSON-RPC message, no session, and no `Mcp-Session-Id`. No protocol state
+ * is retained between calls, so a load balancer can round-robin across
+ * processes with no sticky routing and no shared session store. The one
+ * thing that does outlive a call is the publish state in state.ts, and it
+ * is per-machine disk, not transport state: processes sharing a machine
+ * share it, and machines that do not share it cannot republish each
+ * other's relics.
  *
  * **This does not make Relic hostable.** The transport says how bytes reach
  * the server, not where the server runs. The publishing client must sit next

package/src/install.ts

@@ -82,6 +82,19 @@ export interface ServerSpec {
   readonly env: Readonly<Record<string, string>>;
 }
 
+/**
+ * What `relic-mcp install` writes when the caller supplies no command of
+ * their own. The spec carries a version: `npx -y relic-mcp` bare resolves to
+ * "command not found" on current npx, so a spec without an `@` reproduces a
+ * broken install on every machine that trusts this default.
+ */
+export const DEFAULT_SERVER_SPEC: ServerSpec = {
+  name: 'relic',
+  command: 'npx',
+  args: ['-y', 'relic-mcp@latest'],
+  env: {},
+};
+
 export interface Plan {
   readonly harness: Harness;
   /** The file to write, absent for harnesses driven by their own CLI. */

package/src/installer.ts

@@ -13,6 +13,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  DEFAULT_SERVER_SPEC,
   ExistingEntryError,
   HARNESSES,
   planFor,
@@ -99,12 +100,11 @@ export async function runInstall(argv: readonly string[]): Promise<void> {
     process.exit(2);
   }
 
-  const spec: ServerSpec = {
-    name: options.name,
-    command: 'npx',
-    args: ['-y', 'relic-mcp'],
-    env: {},
-  };
+  // The command comes from the shared default so the versioned npx spec
+  // lives in exactly one place; the name stays the caller's, and the origin
+  // is resolved only on paths that write or print, so a bare `install` can
+  // still just list what it detected.
+  const spec: ServerSpec = { ...DEFAULT_SERVER_SPEC, name: options.name };
 
   if (options.print && options.client === undefined) {
     process.stdout.write(snippetFor(withOrigin(spec, options)));
@@ -230,7 +230,7 @@ function withOrigin(spec: ServerSpec, options: Options): ServerSpec {
     origin = requiredOrigin('--origin', raw);
   } catch (error) {
     process.stderr.write(
-      `${(error as Error).message}\n\nPass --origin https://your-relic-service\n`
+      `${(error as Error).message}\n\nPass --origin https://relik.link\n`
     );
     process.exit(2);
   }

package/src/publish.ts

@@ -14,12 +14,14 @@
 
 import {
   deriveRendererClass,
+  encodeKey,
   encryptRelic,
   generateKey,
   generateRelicId,
   type RendererClass,
   relicUrl,
 } from '@relic/format';
+import { savePublishState } from './state.ts';
 
 /**
  * Codes for the legs the app server is not in.
@@ -27,7 +29,8 @@ import {
  * `spec/service.md` 1.1 owns app-server-originated failures. A purely local
  * file error and a failure on the client-to-storage upload leg have no
  * app-server status, so they get codes here, and these never collide with the
- * server's.
+ * 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.
  */
 export type ClientCode =
   | 'source_not_found'
@@ -36,7 +39,11 @@ export type ClientCode =
   | 'source_unreadable'
   | 'local_size_precheck_failed'
   | 'upload_failed'
-  | 'service_unreachable';
+  | 'service_unreachable'
+  | 'grant_missing_publish_token'
+  | 'no_local_publish_state'
+  | 'local_state_unreadable'
+  | 'local_state_write_failed';
 
 export class PublishError extends Error {
   override readonly name = 'PublishError';
@@ -82,12 +89,25 @@ export interface FileReader {
 export interface PublishInput {
   readonly path: string;
   readonly filename?: string | undefined;
+  /**
+   * A publisher-chosen lifetime in days. Undefined means the relic is kept
+   * until someone deletes it. The field is omitted from the grant entirely
+   * when unset, so the server's default decides, never a zero that happens
+   * to survive the wire.
+   */
+  readonly ttl_days?: number | undefined;
 }
 
 export interface PublishResult {
   readonly url: string;
   readonly relic_id: string;
-  readonly relic_expires_at: string;
+  /**
+   * Always 1 here: a fresh id is a fresh relic, and the client knows it
+   * without asking. Republish counts upward from the local state file.
+   */
+  readonly version: number;
+  /** Null when the relic has no lifetime, which is now the default. */
+  readonly relic_expires_at: string | null;
   readonly renderer_class: RendererClass;
   readonly filename: string;
   readonly resolved_path: string;
@@ -113,8 +133,9 @@ export async function publish(
 
   // 1. Challenge. This returns the cap before a grant is requested, so the
   //    precheck below uses a number that came from the server moments ago
-  //    rather than a compiled-in constant that goes stale. Nothing is kept on
-  //    disk between invocations, so there is no stale local policy.
+  //    rather than a compiled-in constant that goes stale. Policy is never
+  //    cached locally; the one thing publish now keeps on disk is state, in
+  //    state.ts, and it is secrets, not policy.
   const challenge = await postJson(
     deps,
     `${deps.serviceOrigin}/api/challenge`,
@@ -174,6 +195,10 @@ export async function publish(
         publishing_client: deps.clientName,
         declared_size_bytes: source.bytes.length,
         declared_ciphertext_bytes: container.length,
+        // Omitted rather than sent as anything, so an unset lifetime is the
+        // server's default (kept until deleted) and never a value this
+        // client guessed on the publisher's behalf.
+        ...(input.ttl_days === undefined ? {} : { ttl_days: input.ttl_days }),
       });
     } catch (error) {
       if (
@@ -187,40 +212,62 @@ export async function publish(
       }
       throw error;
     }
-
-    // 3. Straight to storage. The ciphertext never transits the app server.
-    const upload = await deps.fetch(String(grant['upload_url']), {
-      method: 'PUT',
-      // The grant signed this exact length, so it is sent explicitly rather
-      // than left to whatever the runtime infers from the body.
-      headers: { 'content-length': String(container.length) },
-      body: container as unknown as BodyInit,
-    });
-    if (!upload.ok) {
+    // The grant hands the publish token over exactly once, here. Without it
+    // this machine can never issue another version of the relic, so a grant
+    // missing it is refused before any bytes move, rather than after the
+    // object exists and the omission is somebody's support ticket.
+    const publishToken = grant['publish_token'];
+    if (typeof publishToken !== 'string' || publishToken.length === 0) {
       throw new PublishError(
-        'upload_failed',
-        `upload returned ${upload.status}`,
-        { relic_id: relicId, status: upload.status }
+        'grant_missing_publish_token',
+        'the grant carried no publish_token, so the relic would never be ' +
+          'republishable from this machine',
+        { relic_id: relicId }
       );
     }
 
-    // 4. Report completion, so the server has a true publish timestamp. A lost
-    //    confirmation is survivable by design: the client already holds the ID
-    //    and the key, so it can still produce a shareable URL.
+    // 3. Straight to storage, then report completion. Both legs are shared
+    //    with republish, because a version-2 object earns the same handling
+    //    a version-1 one does.
+    await putContainer(deps, relicId, String(grant['upload_url']), container);
+    await reportComplete(deps, relicId);
+
+    const url = relicUrl(deps.relicOrigin, relicId, key);
+
+    // 4. Record what a republish needs, before success is reported. State a
+    //    human cannot rebuild by hand only exists once it is on disk; a
+    //    publish that returns without this step is a link that can never be
+    //    updated from here, silently.
     try {
-      await postJson(
-        deps,
-        `${deps.serviceOrigin}/api/relics/${relicId}/complete`,
-        {}
+      await savePublishState(relicId, {
+        key: encodeKey(key),
+        publish_token: publishToken,
+        version: 1,
+      });
+    } catch (error) {
+      // The relic itself is live and the URL works, so both are handed over
+      // in the failure rather than lost to the error path. What failed is
+      // only the local record, but that failure is permanent for this
+      // machine, so it is reported as a failure.
+      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 as Error).message}`,
+        { relic_id: relicId, url }
       );
-    } catch {
-      // Deliberately swallowed. The relic is uploaded and the URL is valid.
     }
 
     return {
-      url: relicUrl(deps.relicOrigin, relicId, key),
+      url,
       relic_id: relicId,
-      relic_expires_at: String(grant['relic_expires_at']),
+      version: 1,
+      // Null is a real state now, the default one; String(null) would hand
+      // the caller the four characters "null" where a date used to be.
+      relic_expires_at:
+        grant['relic_expires_at'] == null
+          ? null
+          : String(grant['relic_expires_at']),
       renderer_class: rendererClass,
       filename,
       resolved_path: source.resolvedPath,
@@ -235,7 +282,7 @@ export async function publish(
   );
 }
 
-async function readSource(
+export async function readSource(
   path: string,
   files: FileReader
 ): Promise<SourceFile> {
@@ -277,7 +324,7 @@ async function readSource(
   return { bytes, basename: files.basename(resolvedPath), resolvedPath };
 }
 
-async function postJson(
+export async function postJson(
   deps: PublishDeps,
   url: string,
   body: unknown
@@ -314,6 +361,60 @@ async function postJson(
   return parsed;
 }
 
+/**
+ * PUT the ciphertext to storage under a signed URL.
+ *
+ * Shared by publish and republish because the leg is identical and its
+ * details are load-bearing: the grant signed this exact length, so it is
+ * sent explicitly rather than left to whatever the runtime infers from the
+ * body.
+ */
+export async function putContainer(
+  deps: PublishDeps,
+  relicId: string,
+  uploadUrl: string,
+  container: Uint8Array
+): Promise<void> {
+  const upload = await deps.fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'content-length': String(container.length) },
+    body: container as unknown as BodyInit,
+  });
+  if (!upload.ok) {
+    throw new PublishError(
+      'upload_failed',
+      `upload returned ${upload.status}`,
+      {
+        relic_id: relicId,
+        status: upload.status,
+      }
+    );
+  }
+}
+
+/**
+ * Report a finished upload, so the server has a true publish timestamp.
+ *
+ * An optimization, never a requirement: the confirmation is the message
+ * that gets lost, which is why the client owns the ID and the key before
+ * anything leaves the machine. The first mint anchors the timestamp if
+ * this call disappears.
+ */
+export async function reportComplete(
+  deps: PublishDeps,
+  relicId: string
+): Promise<void> {
+  try {
+    await postJson(
+      deps,
+      `${deps.serviceOrigin}/api/relics/${relicId}/complete`,
+      {}
+    );
+  } catch {
+    // Deliberately swallowed. The object is uploaded and the link is valid.
+  }
+}
+
 const MIMETYPES: Readonly<Record<string, string>> = {
   md: 'text/markdown',
   markdown: 'text/markdown',
@@ -337,12 +438,19 @@ const MIMETYPES: Readonly<Record<string, string>> = {
   zip: 'application/zip',
   gz: 'application/gzip',
   pdf: 'application/pdf',
+  // Component source declares what it is. text/plain or text/javascript
+  // would both read as `code` on the far side and the relic would render
+  // as escaped source, silently, which is the one outcome a component
+  // author would never guess had happened.
+  jsx: 'text/jsx',
+  tsx: 'text/tsx',
 };
 
 const CLASS_FALLBACK: Readonly<Record<RendererClass, string>> = {
   markdown: 'text/markdown',
   code: 'text/plain',
   html: 'text/html',
+  jsx: 'text/jsx',
   image: 'application/octet-stream',
   media: 'application/octet-stream',
   archive: 'application/octet-stream',

package/src/republish.ts

@@ -0,0 +1,182 @@
+/**
+ * The republish flow: a new version of an existing relic.
+ *
+ * The whole point of a version is that the share URL keeps working, and the
+ * URL's fragment is the key, so a new version MUST be encrypted under the
+ * key the first publish used. That key exists in exactly two places: the
+ * URL, and this machine's publish state. The service holds only a hash of
+ * the publish token and none of the key, so it cannot help. Republishing is
+ * therefore possible only from the machine that published, which is the
+ * boundary the state file draws and this flow enforces before any network.
+ */
+
+import {
+  decodeKey,
+  deriveRendererClass,
+  encryptRelic,
+  isValidRelicId,
+  type RendererClass,
+} from '@relic/format';
+import {
+  guessMimetype,
+  type PublishDeps,
+  PublishError,
+  postJson,
+  putContainer,
+  readSource,
+  reportComplete,
+} from './publish.ts';
+import {
+  loadPublishState,
+  type PublishState,
+  savePublishState,
+} from './state.ts';
+
+export interface RepublishInput {
+  readonly relic_id: string;
+  readonly path: string;
+  readonly filename?: string | undefined;
+  /**
+   * Forwarded on the republish body when set and omitted when unset, the
+   * grant's own convention. A relic's lifetime is fixed at its first grant,
+   * so the service does not read it here today; carrying it keeps the
+   * request honest about what the publisher asked for and needs no client
+   * change if that ever shifts.
+   */
+  readonly ttl_days?: number | undefined;
+}
+
+export interface RepublishResult {
+  readonly relic_id: string;
+  /**
+   * The version just published, counted from the local state file: the
+   * service does not return one, and a publisher only needs to know how
+   * many times this relic has changed.
+   */
+  readonly version: number;
+  /** Null when the relic has no lifetime, which is now the default. */
+  readonly relic_expires_at: string | null;
+  readonly renderer_class: RendererClass;
+  readonly filename: string;
+  readonly resolved_path: string;
+  readonly report_url: string;
+  readonly disclosure_url: string;
+  /**
+   * Deliberately no `url` member. The share URL is unchanged by a new
+   * version, and reprinting it would reprint the key for no new benefit;
+   * the first publish disclosed it once and that is the disclosure that
+   * counts.
+   */
+}
+
+export async function republish(
+  input: RepublishInput,
+  deps: PublishDeps
+): Promise<RepublishResult> {
+  // The gate comes first, before the file is read and before anything can
+  // touch the network: without local state there is nothing to encrypt or
+  // authorize with, and a round trip would only produce a refusal this
+  // machine already knows the reason for.
+  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: PublishState;
+  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) {
+    // 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);
+  }
+
+  const source = await readSource(input.path, deps.files);
+  const filename = input.filename ?? source.basename;
+
+  // Same rule as a first publish: the class comes from bytes in hand, never
+  // from a tool input, so the taxonomy stays machine-attested.
+  const rendererClass = deriveRendererClass(source.bytes, filename);
+
+  // The stored key, not a fresh one. This is the line that keeps the
+  // existing share URL decrypting the new version; a fresh key here would
+  // silently cut every recipient off from content they were told this link
+  // carries.
+  const container = await encryptRelic({
+    content: source.bytes,
+    filename,
+    mimetype: guessMimetype(filename, rendererClass),
+    key: decodeKey(state.key),
+  });
+
+  // 1. The republish grant: same shape as a first grant, authorized by the
+  //    publish token instead of a challenge nonce, aiming the upload at the
+  //    next version's object.
+  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: container.length,
+      ...(input.ttl_days === undefined ? {} : { ttl_days: input.ttl_days }),
+    }
+  );
+
+  // 2. Straight to storage, exactly like a first publish.
+  await putContainer(
+    deps,
+    input.relic_id,
+    String(grant['upload_url']),
+    container
+  );
+
+  // 3. Completion, with the same survivability as a first publish.
+  await reportComplete(deps, input.relic_id);
+
+  // 4. Count the version locally before reporting it. The service does not
+  //    return one, so this file is the only ledger; if the count drifts, the
+  //    number reported drifts with it, and nothing else does.
+  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 as 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']),
+  };
+}