@fennecstudio/x-tkn-mcp 1.2.0 → 1.3.0

package/README.md

@@ -6,9 +6,10 @@ Lets an AI agent hand a secret to a person as a one-time link, with no way to re
 npx -y @fennecstudio/x-tkn-mcp
 ```
 
-- **No read tool.** The server has `create_secret`, `check_status` and
-  `revoke_secret`. Once a secret is handed over, the agent can see whether it
-  was opened and can cancel it. It cannot see the secret again.
+- **No read tool.** The server has `create_secret`, `check_status`,
+  `revoke_secret` and `claim_sandbox`. Once a secret is handed over, the agent
+  can see whether it was opened and can cancel it. It cannot see the secret
+  again.
 - **Encrypted on your machine.** `create_secret` encrypts with AES-256-GCM
   before anything is sent. X-TKN stores only ciphertext. The key travels in the
   link's `#fragment`, which browsers never send to a server.
@@ -37,12 +38,14 @@ Servers that start together share one sandbox: while one mints, it holds a
   Every result on a sandbox key ends with a line giving that end.
 - When it ends, the next call starts a new sandbox and says so. Codes from the
   old one no longer work with `check_status` or `revoke_secret`.
-- A person can keep a sandbox by claiming it at `POST /accounts/claim` with the
-  key from that file. A sandbox has to be claimed before it can be upgraded.
-  The sandbox key still ends on schedule after a claim, so a claimed account
-  goes on with a Developer key created for it and set here.
+- To keep a sandbox, call `claim_sandbox`. It returns a one-time link for the
+  person who should keep it, and the key never leaves this machine. A sandbox
+  has to be claimed before it can be upgraded. The sandbox key still ends on
+  schedule after a claim, so a claimed account goes on with a Developer key
+  created for it and set here.
 - Once a sandbox has spent its operations, the server does not start another,
-  because that would lose the old one's codes. Claim it, or set a key.
+  because that would lose the old one's codes. Call `claim_sandbox`, or set a
+  key.
 
 **For a key that stays**, Developer keys are free: sign up at
 [x-tkn.com](https://x-tkn.com) and create one in the account console. A key in
@@ -84,7 +87,8 @@ Encrypts a secret and returns a link that opens it once.
 | `recipientEmail` | no       | The recipient has to enter a 6-digit code sent to this address. Team and above. Not with `passphrase`.       |
 | `note`           | no       | For your own records in the X-TKN console. Stored unencrypted and never shown to the recipient.               |
 
-Returns the `link`, a `code` for the other two tools, and `expiresAt`.
+Returns the `link`, a `code` for `check_status` and `revoke_secret`, and
+`expiresAt`.
 
 Send a passphrase by a different channel than the link. Anyone holding both can
 open the secret.
@@ -103,6 +107,22 @@ opens spends a whole sandbox in under nine minutes.
 Takes the `code`. Stops the link working, immediately and for good. A secret
 that was already opened stays opened.
 
+### `claim_sandbox`
+
+Takes no arguments. Returns a `claimUrl` and its `expiresAt`: a one-time link a
+person opens to claim the sandbox this server's key belongs to, so the account
+outlives its 24 hours. Claiming keeps the sandbox's secrets.
+
+Give the link only to the person who should keep the sandbox. It works once,
+until `expiresAt`: 30 minutes, or the sandbox's end if that is sooner. Calling
+`claim_sandbox` again voids the earlier link. It is not metered.
+
+The sandbox key still ends when the sandbox would have, claimed or not. For a
+key that lasts, create a Developer key for the account in the account console
+and set `X_TKN_API_KEY`. On a key that is not an unclaimed sandbox (one already
+claimed, merged into another account or ended, or a Developer key), it says so
+and claims nothing.
+
 ## What X-TKN sees
 
 The ciphertext, the expiry, your `note`, and, if you set them, a hash of the

package/dist/index.js

@@ -216,9 +216,9 @@ var XTkn = class _XTkn {
    * clicking a link in an email.
    *
    * The account is capped and temporary: 100 operations and 24 hours. It may
-   * create `secret` tokens, none of which outlives it. {@link XTkn.claim}
-   * turns it into an ordinary Developer account with 10,000 operations a month
-   * and no expiry.
+   * create `secret` tokens, none of which outlives it. {@link XTkn.claim}, or
+   * the link {@link XTkn.createClaimLink} returns, turns it into an ordinary
+   * Developer account with 10,000 operations a month and no expiry.
    *
    * `account.apiKey` is returned once and cannot be read back. Persist it if
    * the process may restart before the account is claimed. It stops working at
@@ -250,9 +250,14 @@ var XTkn = class _XTkn {
    * client authenticates as is the one claimed — there is no account id to
    * pass and no way to name somebody else's.
    *
-   * Existing tokens and keys survive. Throws {@link XTknRequestError} with a
-   * 409 when that email already owns an account; sign in with that one
-   * instead, since merging is not supported.
+   * Existing tokens survive. The sandbox key still ends when the sandbox would
+   * have, so create a Developer key for the account. When that email already
+   * owns an account under the same sign-in, the sandbox is merged into it
+   * instead: the result has `merged: true` and that account's `customerId`,
+   * with no `class` or `monthlyOperations`, and this client's key now acts as
+   * that account until it lapses. Throws {@link XTknRequestError} with a 409
+   * when the email's account is under a different sign-in; sign in with that
+   * one, then claim again.
    *
    * @example
    * ```ts
@@ -269,6 +274,32 @@ var XTkn = class _XTkn {
       headers: { "X-Firebase-Token": firebaseIdToken }
     });
   }
+  /**
+   * Get a one-time link a person opens to claim this sandbox account.
+   *
+   * {@link XTkn.claim} needs the person's sign-in in your own code. This needs
+   * only the sandbox key, so an agent holding the key can hand its person the
+   * link instead. The claim is the same either way: existing tokens survive,
+   * and the sandbox key still ends when the sandbox would have.
+   *
+   * The link works once, until `expiresAt`: 30 minutes, or the sandbox's end
+   * if that is sooner. Minting another voids it. Not counted against the
+   * sandbox's operations.
+   *
+   * Throws {@link XTknError} with a 409 when this key's account is not an
+   * unclaimed sandbox: already claimed, merged into another account, ended, or
+   * never a sandbox.
+   *
+   * @example
+   * ```ts
+   * const { client } = await XTkn.createSandbox()
+   * const { claimUrl, expiresAt } = await client.createClaimLink()
+   * console.log(`Open this before ${expiresAt} to keep the sandbox: ${claimUrl}`)
+   * ```
+   */
+  async createClaimLink() {
+    return this.request("POST", "/accounts/claim");
+  }
   /**
    * Create a token.
    *
@@ -729,19 +760,18 @@ function buildSecretLink(code2, key, options = {}) {
 // src/tools.ts
 var SECRET_TYPE = "secret";
 var SIGNUP_URL = "https://x-tkn.com";
-var SANDBOX_CLAIM_ENDPOINT = "POST /accounts/claim";
 var SANDBOX_EXPIRY_REFUSAL = "Sandbox accounts cannot mint tokens that outlive them.";
 var NO_KEY_MESSAGE = `No X-TKN API key. Set ${API_KEY_ENV_VARS[0]} in this MCP server's environment. To start now with no signup, POST to ${DEFAULT_BASE_URL}/accounts/sandbox for a sandbox key. It lasts 24 hours, and so does every secret it creates. For a key that stays, Developer keys are free: sign up at ${SIGNUP_URL} and create one in the account console.`;
-var SANDBOX_KEY_MESSAGE = `This is a sandbox key. A sandbox account is deleted with its secrets 24 hours after it was created, so no secret it creates can expire later than that. Leave expiresIn out to get the latest expiry it allows. For longer, a person can claim the account at ${SANDBOX_CLAIM_ENDPOINT}, or set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
+var SANDBOX_KEY_MESSAGE = `This is a sandbox key. A sandbox account is deleted with its secrets 24 hours after it was created, so no secret it creates can expire later than that. Leave expiresIn out to get the latest expiry it allows. For longer, call claim_sandbox and give the link it returns to the person who should keep the account, or set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
 function sandboxStartupMessage(path) {
   return `No ${API_KEY_ENV_VARS[0]} set, so this server uses a sandbox: the first tool call reuses the one saved in ${path}, or starts a new one that lasts 24 hours. For a key that stays, set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
 }
 function sandboxLine(sandbox, path) {
   const ends = `Sandbox key: it and its secrets end at ${sandbox.expiresAt}.`;
   if (sandbox.unsaved) {
-    return `${ends} It could not be saved to ${path} (${sandbox.unsaved}), so nobody can claim it, and this server loses it when it stops.`;
+    return `${ends} It could not be saved to ${path} (${sandbox.unsaved}), so this server loses it when it stops. To keep the sandbox, call claim_sandbox before then.`;
   }
-  return `${ends} To keep it, a person claims it at ${SANDBOX_CLAIM_ENDPOINT} with the key saved in ${path}. A sandbox has to be claimed before it can be upgraded.`;
+  return `${ends} Its key is saved in ${path}. To keep the sandbox, call claim_sandbox for a link to give the person who should have it. A sandbox has to be claimed before it can be upgraded.`;
 }
 var SANDBOX_RENEWED_MESSAGE = `A new sandbox started: the last sandbox key expired or X-TKN refused it. Codes create_secret returned before this belong to the old sandbox, and check_status and revoke_secret cannot reach them. If that sandbox was claimed, the account lives on: create a Developer key for it in the account console at ${SIGNUP_URL} and set ${API_KEY_ENV_VARS[0]}.`;
 var SANDBOX_MINT_REFUSED_MESSAGE = `X-TKN is not starting another sandbox from this address for now. Set ${API_KEY_ENV_VARS[0]} in this MCP server's environment to a free Developer key from ${SIGNUP_URL}, or try again in a few minutes.`;
@@ -779,6 +809,16 @@ async function checkStatus(client, code2) {
 async function revokeSecret(client, code2) {
   return statusOf(await client.revokeToken(code2));
 }
+var CLAIMED_KEY_STILL_ENDS = `A claimed sandbox key still ends when the sandbox would have. For a key that lasts, create a Developer key for the account in the account console at ${SIGNUP_URL} and set ${API_KEY_ENV_VARS[0]}.`;
+var NOT_AN_UNCLAIMED_SANDBOX_MESSAGE = "This key is not an unclaimed sandbox, so there is nothing to claim: it is a sandbox key that was already claimed, merged into another account or has ended, or not a sandbox key at all. " + CLAIMED_KEY_STILL_ENDS;
+async function claimSandbox(client) {
+  try {
+    return await client.createClaimLink();
+  } catch (err) {
+    if (err instanceof XTknError && err.status === 409) throw new XTknError(NOT_AN_UNCLAIMED_SANDBOX_MESSAGE, 0);
+    throw err;
+  }
+}
 function statusOf(token) {
   const uses = token.uses ?? 0;
   const opened = token.isUsed ?? (token.maxUses != null && uses >= token.maxUses);
@@ -794,7 +834,7 @@ function statusOf(token) {
 function describeError(err, origin = "key") {
   if (origin === "mint" && err instanceof XTknRateLimitError) return SANDBOX_MINT_REFUSED_MESSAGE;
   if (origin === "sandbox" && err instanceof XTknRateLimitError) {
-    return `X-TKN is refusing more requests on this sandbox key (${err.message}). To go on, a person can claim the sandbox at ${SANDBOX_CLAIM_ENDPOINT}, which lifts its cap, or set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
+    return `X-TKN is refusing more requests on this sandbox key (${err.message}). To go on, call claim_sandbox and give the link it returns to a person: claiming the sandbox lifts its cap. Or set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
   }
   if (origin === "sandbox" && err instanceof XTknAuthError && err.status === 401) {
     return `X-TKN refused this server's sandbox key (${err.message}). Set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
@@ -802,8 +842,7 @@ function describeError(err, origin = "key") {
   if (err instanceof XTknPaymentRequiredError) {
     const plan = err.requiredPlan ? `the ${err.requiredPlan} plan` : "a paid plan";
     if (err.upgradeMethod === "claim") {
-      const claim = err.claimEndpoint ?? SANDBOX_CLAIM_ENDPOINT;
-      return `${err.message} This needs ${plan}, and this is a sandbox key: a person has to claim the account at ${claim} before it can be upgraded.`;
+      return `${err.message} This needs ${plan}, and this is a sandbox key: a person has to claim the account before it can be upgraded. Call claim_sandbox for the link that does it.`;
     }
     const where = err.upgradeUrl ? ` A person can upgrade here: ${err.upgradeUrl}` : "";
     return `${err.message} This needs ${plan}.${where}`;
@@ -1020,7 +1059,7 @@ function isUnauthorized(err) {
 }
 
 // src/version.ts
-var VERSION = "1.2.0";
+var VERSION = "1.3.0";
 
 // src/env.ts
 var USER_AGENT = `x-tkn-mcp/${VERSION}`;
@@ -1061,7 +1100,8 @@ var INSTRUCTIONS = [
   // key should start building, not stop to ask a person to sign up, and since
   // 1.2.0 it need not even fetch a key: `connectionFrom` mints one.
   "With no X_TKN_API_KEY set, this server gets a sandbox key itself on the first tool call: no signup, and it creates real secrets for 24 hours, long enough to build and test the integration.",
-  `For a key that stays, a person can claim the sandbox at ${SANDBOX_CLAIM_ENDPOINT}, or sign up at ${SIGNUP_URL} for a free Developer key.`
+  "To keep a sandbox past its 24 hours, call claim_sandbox and give the link it returns to the person who should keep it.",
+  `Its key still ends on schedule after a claim. For a key that stays, a person signs up at ${SIGNUP_URL} for a free Developer key.`
 ].join(" ");
 var durationField = z.number().int().min(0);
 var expiresIn = z.object({
@@ -1134,6 +1174,19 @@ function createXtknMcpServer(options) {
     },
     ({ code: code2 }) => run(connection, async (client) => status(await revokeSecret(client, code2)))
   );
+  server.registerTool(
+    "claim_sandbox",
+    {
+      title: "Get a link that keeps this sandbox",
+      description: "Get a one-time link a person opens to claim the sandbox this server's key belongs to, so the account outlives its 24 hours and keeps its secrets. Give the link only to the person who should keep it. It works once, for 30 minutes or until the sandbox ends if that is sooner, and calling this again voids the earlier link. The sandbox key itself still ends on schedule: a claimed account goes on with a Developer key created for it. Not metered. On a key that is not an unclaimed sandbox it says so and claims nothing.",
+      outputSchema: {
+        claimUrl: z.string().describe("The one-time link for the person who should keep the sandbox."),
+        expiresAt: z.string().describe("When the link stops working if nobody has used it.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    () => run(connection, async (client) => claimLink(await claimSandbox(client)))
+  );
   return server;
 }
 async function run(connection, work) {
@@ -1155,6 +1208,19 @@ function created(secret) {
   lines.push(`Code for check_status and revoke_secret: ${secret.code}`);
   return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: { ...secret } };
 }
+function claimLink(link) {
+  const lines = [
+    `Claim link: ${link.claimUrl}`,
+    "Give it to the person who should keep this sandbox, and to nobody else: anyone holding it can claim the sandbox.",
+    `It works once, until ${link.expiresAt}: 30 minutes, or the sandbox's end if that is sooner. Calling claim_sandbox again voids it.`,
+    "Claiming keeps the sandbox's secrets.",
+    CLAIMED_KEY_STILL_ENDS
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { claimUrl: link.claimUrl, expiresAt: link.expiresAt }
+  };
+}
 var STATUS_TEXT = {
   waiting: "Waiting: not opened yet.",
   opened: "Opened: the recipient has it, and the link no longer works.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fennecstudio/x-tkn-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "mcpName": "io.github.fennecstudio/x-tkn-mcp",
   "description": "MCP server for X-TKN: hand a secret to a person as a one-time link, encrypted on your machine. No read tool.",
   "keywords": [