@fennecstudio/x-tkn-mcp 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# X-TKN MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets an AI agent hand a secret to a person as a one-time link, with no way to read it back.
+
+```
+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.
+- **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.
+- **Up to 256 KB per secret**: 64 KB on the free Developer plan, 256 KB on Team
+  and Enterprise. Enough for a certificate bundle or a `.env` file, not just a
+  password.
+
+It runs locally over stdio for a reason. A hosted MCP server would receive the
+plaintext before encrypting it, and the whole point is that nobody but the
+recipient can read it.
+
+## Setup
+
+You need Node 20 or later. An X-TKN API key is optional.
+
+**With no key**, the server starts a sandbox on its first tool call, with no
+signup. Nothing is minted at startup. The key is saved in
+`$XDG_CONFIG_HOME/x-tkn/sandbox.json` (`~/.config/x-tkn/sandbox.json` by
+default), the directory 0700 and the file 0600, and later starts reuse it until
+it expires. The key never appears in a tool result or in the server's log.
+Servers that start together share one sandbox: while one mints, it holds a
+`sandbox.json.lock` beside the file, and the others wait for it and use its key.
+
+- A sandbox lasts 24 hours, and so does every secret it creates:
+  `create_secret` refuses an `expiresIn` that runs past the sandbox's end.
+  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.
+- 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.
+
+**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
+`X_TKN_API_KEY` always wins: then nothing is minted and nothing is written.
+
+**Claude Code**
+
+```bash
+claude mcp add x-tkn -- npx -y @fennecstudio/x-tkn-mcp                            # a sandbox
+claude mcp add x-tkn -e X_TKN_API_KEY=your-key -- npx -y @fennecstudio/x-tkn-mcp  # your key
+```
+
+**Claude Desktop, Cursor, Windsurf and other clients** take the same block in
+their MCP config file. Leave `env` out for a sandbox:
+
+```json
+{
+  "mcpServers": {
+    "x-tkn": {
+      "command": "npx",
+      "args": ["-y", "@fennecstudio/x-tkn-mcp"],
+      "env": { "X_TKN_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+## Tools
+
+### `create_secret`
+
+Encrypts a secret and returns a link that opens it once.
+
+| Argument         | Required | What it does                                                                                                   |
+| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `secret`         | yes      | The text to hand over.                                                                                         |
+| `expiresIn`      | no       | `{ days, hours, minutes }`. Defaults to the plan's: 7 days on Developer, 30 on Team. On a sandbox key, defaults to the sandbox's end and cannot be later. |
+| `passphrase`     | no       | The recipient has to type this before the secret opens. 8 to 256 characters. Team and above.                  |
+| `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`.
+
+Send a passphrase by a different channel than the link. Anyone holding both can
+open the secret.
+
+### `check_status`
+
+Takes the `code`. Returns `waiting`, `opened`, `expired` or `revoked`, with
+`openedAt` once it has been opened. It never returns the secret.
+
+Each call is one metered operation, and a sandbox has 100 in all. Call it no
+more often than every 30 seconds: at one call every 5 seconds, a link nobody
+opens spends a whole sandbox in under nine minutes.
+
+### `revoke_secret`
+
+Takes the `code`. Stops the link working, immediately and for good. A secret
+that was already opened stays opened.
+
+## What X-TKN sees
+
+The ciphertext, the expiry, your `note`, and, if you set them, a hash of the
+passphrase or the recipient's email address. The passphrase gates the link and
+plays no part in the encryption. X-TKN never receives the plaintext or the key.
+
+Opening the link uses it up, so give it only to the person it is for. The
+retrieval page takes the key out of the address bar after it decrypts the
+secret. If opening fails, the full link, key included, stays in that browser's
+history.
+
+## Publishing
+
+For whoever ships a release. Run these in order, from this directory. The
+registry steps read what npm holds, so none of them can come before the first.
+
+Keep one version everywhere: `version` in `package.json`, `VERSION` in
+`src/version.ts`, and both `version` fields in `server.json`. Specs fail when
+they disagree. Keep `server.json`'s `description` equal to the first paragraph
+of this README, and no longer than 100 characters, which is the registry's limit.
+
+1. **npm.** `npm run deploy -- --otp=<code>`. That is `npm publish`, and
+   `prepublishOnly` typechecks, tests and builds first. It goes first because
+   the registry reads `mcpName` out of the published package, and npm will not
+   take the same version twice.
+2. **Official MCP Registry.** Install the CLI with `brew install mcp-publisher`,
+   then:
+
+   ```bash
+   mcp-publisher login github
+   mcp-publisher publish
+   ```
+
+   Log in as an Owner of the `fennecstudio` GitHub organization. The registry
+   grants `io.github.fennecstudio/*` to its owners only, and an ordinary member
+   is refused. Check it landed with
+   `curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.fennecstudio/x-tkn-mcp"`.
+3. **Smithery.** `smithery mcp publish`. It does not run bare: Smithery takes a
+   server URL or a pre-built `.mcpb` bundle, and `-n <org>/<server>`. This
+   package serves no URL and builds no bundle, so read `smithery mcp publish --help`
+   and Smithery's publishing docs for the current form before running it.
+4. **Glama and PulseMCP.** Both crawl on their own, so there is nothing to
+   submit. Once the listing appears, claim it on each site.
+
+## Links
+
+- [x-tkn.com](https://x-tkn.com)
+- API reference: [x-tkn.com/docs](https://x-tkn.com/docs)
+- JavaScript SDK: [`@fennecstudio/x-tkn-js`](https://www.npmjs.com/package/@fennecstudio/x-tkn-js)

package/dist/index.js

@@ -0,0 +1,1185 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/env.ts
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+// ../js/src/errors.ts
+var XTknError = class extends Error {
+  /** HTTP status. `0` when the request never got a response. */
+  status;
+  /** Field-level errors, when the API supplied them. */
+  details;
+  /** Parsed response body, for anything the typed fields do not cover. */
+  body;
+  constructor(message, status2, details, body) {
+    super(message);
+    this.name = new.target.name;
+    this.status = status2;
+    this.details = details;
+    this.body = body;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var XTknRequestError = class extends XTknError {
+};
+var XTknAuthError = class extends XTknError {
+};
+var XTknPaymentRequiredError = class extends XTknError {
+  /**
+   * A link a human can act on — Stripe Checkout, or the Billing Portal when the
+   * account already has a subscription. See {@link upgradeMethod}.
+   *
+   * `undefined` when the API could not build one — Stripe unreachable or slow,
+   * or no price configured for the plan — and *always* undefined on an
+   * unclaimed sandbox account, whose next step is {@link claimEndpoint} rather
+   * than a payment. The refusal is still correct; there is just no link to
+   * print. Always handle that case: it is the difference between telling
+   * someone what to do and printing "undefined".
+   */
+  get upgradeUrl() {
+    return this.details?.upgradeUrl;
+  }
+  /**
+   * How this account gets unblocked: `'checkout'` to buy a first subscription,
+   * `'portal'` to change an existing one, `'claim'` to turn an unclaimed
+   * sandbox into a real account first.
+   *
+   * A second subscription would bill twice, so an account that already pays us
+   * changes plan in the portal instead. Both of those are a link a human opens.
+   * `'claim'` is the one that is not: there is no {@link upgradeUrl}, and the
+   * next step is a call your own code makes to {@link claimEndpoint}. Branch on
+   * this rather than assuming a URL is always there.
+   */
+  get upgradeMethod() {
+    return this.details?.upgradeMethod;
+  }
+  /**
+   * Where to claim an unclaimed sandbox account, when {@link upgradeMethod} is
+   * `'claim'`. Undefined otherwise.
+   *
+   * A sandbox is anonymous and reaped within the day, so it cannot hold a
+   * subscription — claiming it is what makes it an account worth buying a plan
+   * for. Claiming grants an ordinary free account, not a paid one, so the plan
+   * in {@link requiredPlan} is still needed afterwards.
+   */
+  get claimEndpoint() {
+    return this.details?.claimEndpoint;
+  }
+  /**
+   * A sentence explaining the claim step, worth showing a human verbatim.
+   * Undefined unless {@link upgradeMethod} is `'claim'`.
+   */
+  get claimReason() {
+    return this.details?.claimReason;
+  }
+  /**
+   * @deprecated No longer sent, so always `undefined`. It carried
+   * {@link upgradeUrl} wrapped as an X-TKN link, which the retrieval page could
+   * not open. Use {@link upgradeUrl}.
+   */
+  get upgradeToken() {
+    return this.details?.upgradeToken;
+  }
+  /** The entitlement that was missing, e.g. `recipientAuth`. */
+  get capability() {
+    return this.details?.capability;
+  }
+  /** The cheapest plan granting it — `team` or `enterprise`. */
+  get requiredPlan() {
+    return this.details?.requiredPlan;
+  }
+  /**
+   * {@link upgradeUrl} works until at least this time. Present only when
+   * {@link upgradeMethod} is `'checkout'`.
+   */
+  get upgradeExpiresAt() {
+    return this.details?.upgradeExpiresAt;
+  }
+};
+var XTknNotFoundError = class extends XTknError {
+};
+var XTknGoneError = class extends XTknError {
+};
+var XTknRateLimitError = class extends XTknError {
+};
+var XTknServerError = class extends XTknError {
+};
+var XTknConnectionError = class extends XTknError {
+  constructor(message, cause) {
+    super(message, 0);
+    this.cause = cause;
+  }
+};
+var XTknConfigError = class extends XTknError {
+  constructor(message) {
+    super(message, 0);
+  }
+};
+function errorForStatus(status2) {
+  if (status2 === 400) return XTknRequestError;
+  if (status2 === 401 || status2 === 403) return XTknAuthError;
+  if (status2 === 402) return XTknPaymentRequiredError;
+  if (status2 === 404) return XTknNotFoundError;
+  if (status2 === 410) return XTknGoneError;
+  if (status2 === 429) return XTknRateLimitError;
+  if (status2 >= 500) return XTknServerError;
+  return XTknError;
+}
+function errorFromResponse(status2, body, statusText) {
+  const record = body && typeof body === "object" ? body : void 0;
+  const message = typeof record?.error === "string" && record.error || typeof record?.message === "string" && record.message || statusText || `Request failed with status ${status2}`;
+  const details = record?.details && typeof record.details === "object" ? record.details : void 0;
+  const Ctor = errorForStatus(status2);
+  return new Ctor(message, status2, details, body);
+}
+
+// ../js/src/duration.ts
+var MS = {
+  seconds: 1e3,
+  minutes: 6e4,
+  hours: 36e5,
+  days: 864e5
+};
+function durationToMs(duration) {
+  let total = 0;
+  let seen = false;
+  for (const unit of ["days", "hours", "minutes", "seconds"]) {
+    const value = duration?.[unit];
+    if (value === void 0 || value === null) continue;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new XTknConfigError(`Duration field "${unit}" must be a finite number`);
+    }
+    total += value * MS[unit];
+    seen = true;
+  }
+  if (!seen) {
+    throw new XTknConfigError("Duration must set at least one of days, hours, minutes or seconds");
+  }
+  return total;
+}
+function durationToSeconds(duration) {
+  return Math.round(durationToMs(duration) / 1e3);
+}
+function expiryFromDuration(duration, from = /* @__PURE__ */ new Date()) {
+  return new Date(from.getTime() + durationToMs(duration));
+}
+function resolveExpiry(expiresAt, expiresIn2) {
+  if (expiresAt !== void 0 && expiresIn2 !== void 0) {
+    throw new XTknConfigError("Pass either expiresAt or expiresIn, not both");
+  }
+  if (expiresIn2 !== void 0) return expiryFromDuration(expiresIn2).toISOString();
+  if (expiresAt === void 0) return void 0;
+  const date = expiresAt instanceof Date ? expiresAt : new Date(expiresAt);
+  if (Number.isNaN(date.getTime())) {
+    throw new XTknConfigError(`expiresAt is not a valid date: ${String(expiresAt)}`);
+  }
+  return date.toISOString();
+}
+
+// ../js/src/client.ts
+var DEFAULT_BASE_URL = "https://api.x-tkn.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var API_KEY_ENV_VARS = ["X_TKN_API_KEY", "X_TKN_API_KEY_ID"];
+function envApiKey() {
+  const env = typeof process !== "undefined" ? process.env : void 0;
+  if (!env) return void 0;
+  for (const name of API_KEY_ENV_VARS) {
+    const value = env[name];
+    if (value) return value;
+  }
+  return void 0;
+}
+function compact(input) {
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+var XTkn = class _XTkn {
+  options;
+  baseUrl;
+  constructor(options = {}) {
+    this.options = options;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+  /**
+   * Mint a sandbox account and return a client already holding its key.
+   *
+   * No signup, no inbox, no key of your own — which is the point. This is the
+   * one call on the API with no credential, so it is the one way a coding
+   * agent gets from `npm install` to a working request without a human
+   * 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.
+   *
+   * `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
+   * `account.expiresAt` whether or not the account was claimed: a claimed
+   * account needs a Developer key of its own, created in the console.
+   *
+   * @example
+   * ```ts
+   * const { client, account } = await XTkn.createSandbox()
+   * console.log(`${account.limits.monthlyOperations} ops until ${account.expiresAt}`)
+   *
+   * const token = await client.createToken({ maxUses: 1, expiresIn: { minutes: 15 } })
+   * ```
+   */
+  static async createSandbox(options = {}) {
+    const bootstrap = new _XTkn(options);
+    const account = await bootstrap.request(
+      "POST",
+      "/accounts/sandbox",
+      void 0,
+      { auth: false }
+    );
+    return { client: new _XTkn({ ...options, apiKey: account.apiKey }), account };
+  }
+  /**
+   * Keep this sandbox account permanently.
+   *
+   * Takes a Firebase ID token for whoever is claiming it. The account this
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const { client } = await XTkn.createSandbox()
+   * // ... later, once a human has signed in ...
+   * await client.claim(await firebaseUser.getIdToken())
+   * ```
+   */
+  async claim(firebaseIdToken) {
+    if (!firebaseIdToken) {
+      throw new XTknConfigError("A Firebase ID token is required to claim an account");
+    }
+    return this.request("POST", "/accounts/claim", void 0, {
+      headers: { "X-Firebase-Token": firebaseIdToken }
+    });
+  }
+  /**
+   * Create a token.
+   *
+   * The returned {@link Token.code} is the only copy — the server stores a hash
+   * of it and cannot return it again.
+   *
+   * @throws {XTknConfigError} if both `expiresAt` and `expiresIn` are given.
+   * @throws {XTknRequestError} if a field fails server validation.
+   *
+   * @example
+   * ```ts
+   * const token = await xtkn.createToken({
+   *   type: 'password-reset',
+   *   refId: user.id,
+   *   maxUses: 1,
+   *   expiresIn: { minutes: 30 },
+   * })
+   * await sendEmail(user.email, `https://app.example.com/reset#${token.code}`)
+   * ```
+   */
+  async createToken(input = {}) {
+    const { expiresAt, expiresIn: expiresIn2, idleTimeout, ...rest } = input;
+    const body = compact({
+      ...rest,
+      expiresAt: resolveExpiry(expiresAt, expiresIn2),
+      idleTimeoutSeconds: idleTimeout === void 0 ? void 0 : durationToSeconds(idleTimeout)
+    });
+    return this.request("POST", "/tokens/create", body);
+  }
+  /**
+   * Read a token without consuming a use.
+   *
+   * @throws {XTknNotFoundError} if no token with this code belongs to your account.
+   *
+   * @example
+   * ```ts
+   * const token = await xtkn.readToken(code)
+   * if (!token.isActive) return renderExpired()
+   * ```
+   *
+   * On a live sliding token — one created with
+   * {@link CreateTokenInput.idleTimeout} — a read counts as activity and moves
+   * its expiry forward like a redeem, without consuming a use.
+   */
+  async readToken(code2) {
+    return this.request("GET", `/tokens/${encodeURIComponent(this.requireCode(code2))}/read`);
+  }
+  /**
+   * Redeem a token, consuming one use.
+   *
+   * Scope the redeem wherever you can. `refId` confines the lookup to the
+   * identity the code was issued for, which is what bounds guessing; `type`
+   * stops a redemption consuming a different kind of code held by the same
+   * identity.
+   *
+   * @throws {XTknNotFoundError} if the code is wrong, or does not match the scoping.
+   * @throws {XTknGoneError} if the token is revoked, expired, or out of uses.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   const token = await xtkn.redeemToken(code, { refId: user.id, type: 'password-reset' })
+   *   await resetPassword(user, token.payload)
+   * } catch (err) {
+   *   if (err instanceof XTknGoneError) return renderLinkAlreadyUsed()
+   *   throw err
+   * }
+   * ```
+   */
+  async redeemToken(code2, options = {}) {
+    return this.request(
+      "PATCH",
+      `/tokens/${encodeURIComponent(this.requireCode(code2))}/redeem`,
+      compact({ refId: options.refId, type: options.type })
+    );
+  }
+  /**
+   * Change a token's mutable fields. Omitted fields are left alone.
+   *
+   * `description` is not updatable — the server's update handler ignores it.
+   *
+   * @throws {XTknConfigError} if both `expiresAt` and `expiresIn` are given.
+   * @throws {XTknNotFoundError} if no token with this code belongs to your account.
+   */
+  async updateToken(code2, updates = {}) {
+    const { expiresAt, expiresIn: expiresIn2, ...rest } = updates;
+    const body = compact({ ...rest, expiresAt: resolveExpiry(expiresAt, expiresIn2) });
+    return this.request(
+      "PATCH",
+      `/tokens/${encodeURIComponent(this.requireCode(code2))}/update`,
+      body
+    );
+  }
+  /**
+   * Push a token's expiry out to `duration` from now.
+   *
+   * Measured from the current time, not from the existing expiry, so calling
+   * this on an already-expired token revives it rather than extending from a
+   * date in the past.
+   *
+   * On a sliding token this moves the hard expiry,
+   * {@link Token.absoluteExpiresAt}, and restarts the idle window from now
+   * inside it. A sliding token does not need this to stay alive while in use.
+   *
+   * @example
+   * ```ts
+   * await xtkn.extendExpiration(sessionCode, { hours: 2 })
+   * ```
+   */
+  async extendExpiration(code2, duration) {
+    return this.updateToken(code2, { expiresAt: expiryFromDuration(duration) });
+  }
+  /**
+   * Revoke a token. Permanent, and takes effect immediately.
+   *
+   * @throws {XTknNotFoundError} if no token with this code belongs to your account.
+   */
+  async revokeToken(code2) {
+    return this.request(
+      "PATCH",
+      `/tokens/${encodeURIComponent(this.requireCode(code2))}/revoke`
+    );
+  }
+  /**
+   * Revoke every token matching a filter.
+   *
+   * One call revokes a bounded number of tokens. When
+   * {@link BulkRevokeResult.hasMore} comes back true there are more matches
+   * than were revoked — call again with the same filter until it is false.
+   *
+   * @throws {XTknConfigError} if neither `type` nor `refId` is set. An empty
+   * filter would mean "revoke everything", which is never worth allowing by
+   * omission.
+   *
+   * @example Log a user out everywhere
+   * ```ts
+   * let result
+   * do {
+   *   result = await xtkn.revokeTokens({ refId: user.id, type: 'session' })
+   * } while (result.hasMore)
+   * ```
+   */
+  async revokeTokens(filter) {
+    if (!filter?.type && !filter?.refId) {
+      throw new XTknConfigError("revokeTokens requires at least one of type or refId");
+    }
+    return this.request(
+      "PATCH",
+      "/tokens/revoke",
+      compact({ type: filter.type, refId: filter.refId })
+    );
+  }
+  /**
+   * Permanently delete a token. Prefer {@link XTkn.revokeToken} unless you need
+   * the row gone — a revoked token still reports why a redemption failed,
+   * a deleted one is indistinguishable from one that never existed.
+   *
+   * @throws {XTknNotFoundError} if no token with this code belongs to your account.
+   */
+  async deleteToken(code2) {
+    await this.request("DELETE", `/tokens/${encodeURIComponent(this.requireCode(code2))}`);
+  }
+  /**
+   * List your tokens, newest first.
+   *
+   * Only `type`, `refId` and `isRevoked` are filterable; the server drops
+   * anything else in `where` without complaining, so a typo widens the result
+   * rather than erroring. `limit` is capped at 100.
+   *
+   * Codes are not exposed as a filter. The API does accept one, hashing the
+   * value to match `sha256(code)`, but it returns at most the single token you
+   * already hold the code for — {@link XTkn.readToken} does that directly.
+   *
+   * @example
+   * ```ts
+   * const { tokens, count } = await xtkn.listTokens({
+   *   where: { refId: user.id, isRevoked: false },
+   *   limit: 50,
+   * })
+   * ```
+   */
+  async listTokens(options = {}) {
+    const body = compact({
+      where: options.where,
+      sort: options.sort,
+      page: options.page,
+      limit: options.limit
+    });
+    return this.request("POST", "/tokens/list", body);
+  }
+  // ── internals ───────────────────────────────────────────────────────────
+  /**
+   * Read this key's plan, limits and quota position.
+   *
+   * Call it to find out what you may do *before* doing it. The alternative is
+   * discovering each fence by tripping it, which costs a failed request and —
+   * for anything with a side effect — leaves you guessing what did and did not
+   * happen.
+   *
+   * Cheap: it reaches nothing outside our own database.
+   *
+   * @example
+   * ```ts
+   * const me = await xtkn.account()
+   * if (!me.limits.recipientAuth) {
+   *   // Do not even try to gate this secret; the create would 402.
+   *   return sendUngated()
+   * }
+   * if (me.usage.remaining !== null && me.usage.remaining < batch.length) {
+   *   return console.warn(`Only ${me.usage.remaining} operations left this month`)
+   * }
+   * ```
+   */
+  async account() {
+    return this.request("GET", "/account");
+  }
+  /**
+   * Get a Checkout link a human can pay through.
+   *
+   * **This does not upgrade anything.** It creates a link. The plan changes
+   * only once Stripe reports the completed subscription back to us — poll
+   * {@link account} if you need to know when.
+   *
+   * Paying is deliberately left to a person: recurring-subscription consent is
+   * the consent an agent has the weakest claim to give, and a card challenge is
+   * browser-shaped.
+   *
+   * Say what you want one of three ways — name a `tier`, name the `capability`
+   * you were refused, or pass nothing and get the next plan up.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await xtkn.createWebhookEndpoint(url)
+   * } catch (err) {
+   *   if (err instanceof XTknPaymentRequiredError) {
+   *     const intent = await xtkn.upgradeIntent({ capability: err.capability as never })
+   *     console.log(`Ask someone to pay here, within 30 minutes: ${intent.url}`)
+   *   }
+   * }
+   * ```
+   */
+  async upgradeIntent(options = {}) {
+    return this.request("POST", "/billing/upgrade-intent", compact({ ...options }));
+  }
+  requireCode(code2) {
+    if (typeof code2 !== "string" || code2.length === 0) {
+      throw new XTknConfigError("A token code is required");
+    }
+    return code2;
+  }
+  resolveApiKey() {
+    const key = this.options.apiKey ?? envApiKey();
+    if (!key) {
+      throw new XTknConfigError(
+        `No API key. Pass { apiKey } to the XTkn constructor, or set ${API_KEY_ENV_VARS[0]}.`
+      );
+    }
+    return key;
+  }
+  /**
+   * Issue one request and unwrap the response.
+   *
+   * Two things v1 got wrong happen here. Non-2xx responses throw instead of
+   * being handed back typed as data, and the `{ success, data }` envelope is
+   * unwrapped so callers get the token rather than the wrapper around it.
+   */
+  async request(method, path, body, options = {}) {
+    const doFetch = this.options.fetch ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+      throw new XTknConfigError(
+        "No fetch implementation. Node 18+ provides one; on older runtimes pass { fetch }."
+      );
+    }
+    const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = timeoutMs > 0 ? new AbortController() : void 0;
+    const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+    let response;
+    let raw;
+    try {
+      response = await doFetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          ...this.options.headers,
+          "Content-Type": "application/json",
+          // Resolved only when the endpoint needs it. `POST /accounts/sandbox`
+          // is the one route with no credential, and calling `resolveApiKey`
+          // there would throw the "no API key" error at the exact caller who
+          // is asking for one.
+          ...options.auth === false ? {} : { Authorization: this.resolveApiKey() },
+          ...options.headers
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller?.signal
+      });
+      raw = response.status === 204 ? "" : await response.text();
+    } catch (err) {
+      if (err instanceof XTknError) throw err;
+      const aborted = err?.name === "AbortError";
+      throw new XTknConnectionError(
+        aborted ? `Request to ${path} timed out after ${timeoutMs}ms` : `Request to ${path} failed`,
+        err
+      );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    const parsed = raw ? safeJsonParse(raw) : void 0;
+    if (!response.ok) throw errorFromResponse(response.status, parsed, response.statusText);
+    return unwrap(parsed);
+  }
+};
+function safeJsonParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function unwrap(parsed) {
+  if (parsed && typeof parsed === "object" && "success" in parsed && "data" in parsed) {
+    return parsed.data;
+  }
+  return parsed;
+}
+
+// src/connection.ts
+function keyConnection(client) {
+  return {
+    async call(work) {
+      try {
+        return { ok: true, value: await work(client), notes: [] };
+      } catch (error) {
+        return { ok: false, error, origin: "key", notes: [] };
+      }
+    }
+  };
+}
+
+// src/sandbox.ts
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+// ../js/src/vendor/token-envelope.ts
+var PREFIX_V1 = "xtkn.v1.";
+var NONCE_BYTES = 12;
+var TAG_BYTES = 16;
+var KEY_BYTES = 32;
+var B64URL = /^[A-Za-z0-9_-]*$/;
+var B64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function encodeBase64Url(bytes) {
+  let binary = "";
+  const CHUNK = 32768;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeBase64Url(value) {
+  if (!B64URL.test(value)) return null;
+  const tail = value.length % 4;
+  if (tail === 1) return null;
+  if (tail !== 0) {
+    const slack = tail === 2 ? 15 : 3;
+    const last = B64URL_ALPHABET.indexOf(value[value.length - 1]);
+    if (last < 0 || (last & slack) !== 0) return null;
+  }
+  const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  try {
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+    return out;
+  } catch {
+    return null;
+  }
+}
+function buildEnvelope(nonce, ciphertext) {
+  if (nonce.length !== NONCE_BYTES) {
+    throw new Error(`nonce must be ${NONCE_BYTES} bytes, got ${nonce.length}`);
+  }
+  if (ciphertext.length <= TAG_BYTES) {
+    throw new Error(`ciphertext must exceed the ${TAG_BYTES}-byte tag`);
+  }
+  return `${PREFIX_V1}${encodeBase64Url(nonce)}.${encodeBase64Url(ciphertext)}`;
+}
+
+// ../js/src/vendor/token-crypto.ts
+var ALGORITHM = "AES-GCM";
+var TAG_BITS = TAG_BYTES * 8;
+function subtle() {
+  const c = globalThis.crypto;
+  if (!c?.subtle) {
+    throw new Error("WebCrypto is unavailable \u2014 token encryption needs a secure context");
+  }
+  return c.subtle;
+}
+function generateKey() {
+  return globalThis.crypto.getRandomValues(new Uint8Array(KEY_BYTES));
+}
+function encodeKey(key) {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`key must be ${KEY_BYTES} bytes, got ${key.length}`);
+  }
+  return encodeBase64Url(key);
+}
+function decodeKey(value) {
+  const bytes = decodeBase64Url(value);
+  if (!bytes || bytes.length !== KEY_BYTES) return null;
+  return bytes;
+}
+async function importKey(key, usage) {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`key must be ${KEY_BYTES} bytes, got ${key.length}`);
+  }
+  return subtle().importKey("raw", key, ALGORITHM, false, [usage]);
+}
+async function encryptPayload(plaintext, key) {
+  const nonce = globalThis.crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const cryptoKey = await importKey(key, "encrypt");
+  const ciphertext = await subtle().encrypt(
+    { name: ALGORITHM, iv: nonce, tagLength: TAG_BITS },
+    cryptoKey,
+    new TextEncoder().encode(plaintext)
+  );
+  return buildEnvelope(nonce, new Uint8Array(ciphertext));
+}
+
+// ../js/src/seal.ts
+var DEFAULT_SECRET_LINK_ORIGIN = "https://x-tkn.com";
+async function sealSecret(plaintext) {
+  if (typeof plaintext !== "string") {
+    throw new XTknConfigError("sealSecret takes a string; JSON.stringify anything else first");
+  }
+  if (!plaintext) {
+    throw new XTknConfigError("sealSecret needs a secret to seal; got an empty string");
+  }
+  if (!globalThis.crypto?.subtle) {
+    throw new XTknConfigError(
+      "sealSecret needs a global WebCrypto (globalThis.crypto): Node 20 or later, a browser, Deno, Bun or Workers"
+    );
+  }
+  const key = generateKey();
+  return { envelope: await encryptPayload(plaintext, key), key: encodeKey(key) };
+}
+function buildSecretLink(code2, key, options = {}) {
+  if (typeof code2 !== "string" || !code2) {
+    throw new XTknConfigError("A token code is required");
+  }
+  if (typeof key !== "string" || !decodeKey(key)) {
+    throw new XTknConfigError("key must be the key sealSecret returned: 43 characters of base64url");
+  }
+  const origin = (options.origin ?? DEFAULT_SECRET_LINK_ORIGIN).replace(/\/+$/, "");
+  return `${origin}/s/#${code2}.${key}`;
+}
+
+// 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}.`;
+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} 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.`;
+}
+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.`;
+async function createSecret(client, args) {
+  if (args.passphrase !== void 0 && args.recipientEmail !== void 0) {
+    throw new XTknConfigError("Set passphrase or recipientEmail, not both. A secret takes one recipient check.");
+  }
+  const { envelope, key } = await sealSecret(args.secret);
+  const input = {
+    type: SECRET_TYPE,
+    payload: envelope,
+    maxUses: 1,
+    expiresIn: args.expiresIn,
+    description: args.note
+  };
+  if (args.passphrase !== void 0) {
+    input.authMethod = "passphrase";
+    input.authPassphrase = args.passphrase;
+  } else if (args.recipientEmail !== void 0) {
+    input.authMethod = "email";
+    input.authEmail = args.recipientEmail;
+  }
+  const token = await client.createToken(input);
+  if (!token.code) throw new XTknError("X-TKN created the secret but returned no code for it", 0);
+  return {
+    link: buildSecretLink(token.code, key),
+    code: token.code,
+    expiresAt: token.expiresAt ?? null,
+    recipientAuth: input.authMethod ?? null
+  };
+}
+async function checkStatus(client, code2) {
+  return statusOf(await client.readToken(code2));
+}
+async function revokeSecret(client, code2) {
+  return statusOf(await client.revokeToken(code2));
+}
+function statusOf(token) {
+  const uses = token.uses ?? 0;
+  const opened = token.isUsed ?? (token.maxUses != null && uses >= token.maxUses);
+  const status2 = opened ? "opened" : token.isRevoked ? "revoked" : token.isExpired ? "expired" : "waiting";
+  return {
+    status: status2,
+    type: token.type ?? null,
+    openedAt: uses > 0 ? token.lastUsedAt ?? null : null,
+    expiresAt: token.expiresAt ?? null,
+    createdAt: token.createdAt ?? null
+  };
+}
+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}.`;
+  }
+  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}.`;
+  }
+  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.`;
+    }
+    const where = err.upgradeUrl ? ` A person can upgrade here: ${err.upgradeUrl}` : "";
+    return `${err.message} This needs ${plan}.${where}`;
+  }
+  if (err instanceof XTknRequestError && err.message.startsWith(SANDBOX_EXPIRY_REFUSAL)) return SANDBOX_KEY_MESSAGE;
+  if (err instanceof XTknConfigError && err.message.startsWith("No API key")) return NO_KEY_MESSAGE;
+  if (err instanceof XTknAuthError && err.status === 401) {
+    return `X-TKN refused the API key in ${API_KEY_ENV_VARS[0]} (${err.message}). It may be mistyped or revoked.`;
+  }
+  if (err instanceof XTknNotFoundError) {
+    return "No secret with that code on this account. Use the code create_secret returned.";
+  }
+  if (err instanceof XTknRateLimitError) return `X-TKN is refusing more requests for now: ${err.message}`;
+  if (err instanceof XTknConnectionError) return `Could not reach X-TKN: ${err.message}`;
+  if (err instanceof XTknError) return err.status ? `X-TKN answered ${err.status}: ${err.message}` : err.message;
+  return "The tool failed unexpectedly.";
+}
+
+// src/sandbox.ts
+async function readSandboxCache(path, baseUrl) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+  if (!parsed || typeof parsed !== "object") return void 0;
+  const { apiKey, expiresAt, baseUrl: cachedBaseUrl } = parsed;
+  if (typeof apiKey !== "string" || apiKey === "") return void 0;
+  if (typeof expiresAt !== "string" || Number.isNaN(Date.parse(expiresAt))) return void 0;
+  if (cachedBaseUrl !== baseUrl) return void 0;
+  return { apiKey, expiresAt, baseUrl };
+}
+async function writeSandboxCache(path, sandbox) {
+  await prepareDir(dirname(path));
+  const temp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(temp, `${JSON.stringify(sandbox, null, 2)}
+`, { mode: 384, flag: "wx" });
+    await rename(temp, path);
+  } catch (err) {
+    await rm(temp, { force: true });
+    throw err;
+  }
+}
+async function prepareDir(dir) {
+  await mkdir(dir, { recursive: true, mode: 448 });
+  await chmod(dir, 448);
+}
+var LOCK_STALE_MS = DEFAULT_TIMEOUT_MS + 1e4;
+var LOCK_POLL_MS = 25;
+async function withCacheLock(path, work) {
+  const lock = `${path}.lock`;
+  const token = randomBytes(8).toString("hex");
+  if (!await acquireLock(path, lock, token)) return work();
+  try {
+    return await work();
+  } finally {
+    await releaseLock(lock, token);
+  }
+}
+async function acquireLock(path, lock, token) {
+  try {
+    await prepareDir(dirname(path));
+    for (; ; ) {
+      try {
+        await writeFile(lock, token, { mode: 384, flag: "wx" });
+        return true;
+      } catch (err) {
+        if (err.code !== "EEXIST") return false;
+      }
+      let age;
+      try {
+        age = Date.now() - (await stat(lock)).mtimeMs;
+      } catch (err) {
+        if (err.code === "ENOENT") continue;
+        return false;
+      }
+      if (age > LOCK_STALE_MS) await rm(lock, { force: true });
+      else await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+  } catch {
+    return false;
+  }
+}
+async function releaseLock(lock, token) {
+  try {
+    if (await readFile(lock, "utf8") === token) await rm(lock, { force: true });
+  } catch {
+  }
+}
+var SandboxConnection = class {
+  path;
+  baseUrl;
+  clientOptions;
+  now;
+  held;
+  pending;
+  constructor(options) {
+    this.path = options.path;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.clientOptions = { baseUrl: this.baseUrl, fetch: options.fetch, headers: options.headers };
+    this.now = options.now ?? Date.now;
+  }
+  async call(work) {
+    let acquired;
+    try {
+      acquired = await this.acquire();
+    } catch (error) {
+      return { ok: false, error, origin: "mint", notes: [] };
+    }
+    const { sandbox, fresh, renewed } = acquired;
+    try {
+      return { ok: true, value: await work(this.clientFor(sandbox)), notes: this.notes(sandbox, renewed) };
+    } catch (error) {
+      if (fresh || !isUnauthorized(error)) {
+        return { ok: false, error, origin: "sandbox", notes: this.notes(sandbox, renewed) };
+      }
+    }
+    let replacement;
+    try {
+      replacement = await this.replace(sandbox);
+    } catch (error) {
+      return { ok: false, error, origin: "mint", notes: [] };
+    }
+    try {
+      return { ok: true, value: await work(this.clientFor(replacement)), notes: this.notes(replacement, true) };
+    } catch (error) {
+      return { ok: false, error, origin: "sandbox", notes: this.notes(replacement, true) };
+    }
+  }
+  /**
+   * The sandbox for this call: the one held while it lasts, then the file's,
+   * then a new one.
+   *
+   * `fresh` is whether it was minted for this call. `renewed` is whether it
+   * replaced a sandbox this server or the file had, so the codes from that one
+   * are gone.
+   */
+  async acquire() {
+    const held = this.held;
+    if (held && !this.expired(held)) return { sandbox: held, fresh: false, renewed: false };
+    const sandbox = await this.single(() => this.load());
+    return {
+      sandbox,
+      fresh: sandbox.minted,
+      renewed: held ? sandbox.apiKey !== held.apiKey : sandbox.replaced
+    };
+  }
+  async load() {
+    const cached = await readSandboxCache(this.path, this.baseUrl);
+    if (cached && !this.expired(cached)) return this.adopt(cached, false);
+    return withCacheLock(this.path, async () => {
+      const again = await readSandboxCache(this.path, this.baseUrl);
+      if (again && !this.expired(again)) return this.adopt(again, cached !== void 0);
+      return this.mint(cached !== void 0 || again !== void 0);
+    });
+  }
+  /**
+   * A sandbox in place of `refused`, unless a concurrent call, or another
+   * server, already made one.
+   */
+  replace(refused) {
+    return this.single(async () => {
+      const held = this.held;
+      if (held && held.apiKey !== refused.apiKey && !this.expired(held)) return held;
+      return withCacheLock(this.path, async () => {
+        const cached = await readSandboxCache(this.path, this.baseUrl);
+        if (cached && cached.apiKey !== refused.apiKey && !this.expired(cached)) return this.adopt(cached, true);
+        return this.mint(true);
+      });
+    });
+  }
+  /** Hold a sandbox another server minted, which this one found in the file. */
+  adopt(cached, replaced) {
+    this.held = { ...cached, minted: false, replaced };
+    return this.held;
+  }
+  async mint(replaced) {
+    const { account } = await XTkn.createSandbox(this.clientOptions);
+    if (typeof account?.apiKey !== "string" || !account.apiKey || Number.isNaN(Date.parse(account.expiresAt))) {
+      throw new XTknError("X-TKN started a sandbox but returned no key or expiry for it", 0);
+    }
+    const sandbox = { apiKey: account.apiKey, expiresAt: account.expiresAt, baseUrl: this.baseUrl };
+    let unsaved;
+    try {
+      await writeSandboxCache(this.path, sandbox);
+    } catch (err) {
+      unsaved = err?.code ?? "write failed";
+    }
+    this.held = { ...sandbox, minted: true, replaced, unsaved };
+    return this.held;
+  }
+  /** One mint or file read at a time. Concurrent first calls share the one sandbox. */
+  single(start) {
+    this.pending ??= start().finally(() => {
+      this.pending = void 0;
+    });
+    return this.pending;
+  }
+  expired(sandbox) {
+    return Date.parse(sandbox.expiresAt) <= this.now();
+  }
+  clientFor(sandbox) {
+    return new XTkn({ ...this.clientOptions, apiKey: sandbox.apiKey });
+  }
+  notes(sandbox, renewed) {
+    const line = sandboxLine(sandbox, this.path);
+    return renewed ? [SANDBOX_RENEWED_MESSAGE, line] : [line];
+  }
+};
+function isUnauthorized(err) {
+  return err instanceof XTknAuthError && err.status === 401;
+}
+
+// src/version.ts
+var VERSION = "1.2.0";
+
+// src/env.ts
+var USER_AGENT = `x-tkn-mcp/${VERSION}`;
+function apiKeyFrom(env) {
+  for (const name of API_KEY_ENV_VARS) {
+    if (env[name]) return env[name];
+  }
+  return void 0;
+}
+function clientFrom(env, options = {}) {
+  return new XTkn({ ...options, apiKey: apiKeyFrom(env), headers: { "User-Agent": USER_AGENT } });
+}
+function sandboxCachePath(env, home = homedir()) {
+  const xdg = env.XDG_CONFIG_HOME;
+  const configHome = xdg && isAbsolute(xdg) ? xdg : join(home, ".config");
+  return join(configHome, "x-tkn", "sandbox.json");
+}
+function connectionFrom(env, options = {}) {
+  const { home, now, ...client } = options;
+  if (apiKeyFrom(env)) return keyConnection(clientFrom(env, client));
+  return new SandboxConnection({
+    ...client,
+    path: sandboxCachePath(env, home),
+    headers: { "User-Agent": USER_AGENT },
+    now
+  });
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+var INSTRUCTIONS = [
+  "X-TKN hands a secret to a person as a one-time link.",
+  "create_secret encrypts the secret on this machine. X-TKN stores only ciphertext, and the key travels in the link after the #.",
+  "There is no tool to read a secret back. After handing one over you can check whether it was opened (check_status) or cancel it (revoke_secret).",
+  "Give the link only to the person it is for: opening it uses it up. If you set a passphrase, send it by a different channel than the link.",
+  // Read at connect time, before any tool call can say it. An agent with no
+  // 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.`
+].join(" ");
+var durationField = z.number().int().min(0);
+var expiresIn = z.object({
+  days: durationField.optional(),
+  hours: durationField.optional(),
+  minutes: durationField.optional()
+}).refine((d) => (d.days ?? 0) + (d.hours ?? 0) + (d.minutes ?? 0) > 0, {
+  message: "expiresIn needs at least one field above zero"
+});
+var code = z.string().min(1).describe("The code create_secret returned for this secret.");
+var statusShape = {
+  status: z.enum(["waiting", "opened", "expired", "revoked"]).describe("waiting: not opened yet. opened: the recipient has it, and the link no longer works."),
+  type: z.string().nullable(),
+  openedAt: z.string().nullable(),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string().nullable()
+};
+function createXtknMcpServer(options) {
+  const connection = "connection" in options ? options.connection : keyConnection(options.client);
+  const server = new McpServer({ name: "x-tkn", title: "X-TKN", version: VERSION }, { instructions: INSTRUCTIONS });
+  server.registerTool(
+    "create_secret",
+    {
+      title: "Create a one-time secret link",
+      description: "Turn a secret (a password, API key, recovery code or private note) into a link a person opens once. The secret is encrypted on this machine before anything is sent, and X-TKN never holds the key. The link stops working once opened, or at its expiry. You cannot read the secret back afterwards: this server has no read tool. Returns the link and a code for check_status and revoke_secret. Up to 64 KB on the free Developer plan, 256 KB on Team and Enterprise.",
+      inputSchema: {
+        secret: z.string().min(1).describe("The secret to hand over. It is encrypted before it leaves this machine."),
+        expiresIn: expiresIn.optional().describe(
+          "How long the link works if nobody opens it. Defaults to the plan's: 7 days on Developer, 30 on Team. On a sandbox key it cannot run past the sandbox, which ends 24 hours after it was created, and defaults to that end."
+        ),
+        passphrase: z.string().min(8).max(256).optional().describe(
+          "Make the recipient type this before the secret opens. Send it by a different channel than the link. X-TKN stores a hash of it, which gates the link and plays no part in the encryption. Team plan and above."
+        ),
+        recipientEmail: z.email().optional().describe(
+          "Make the recipient enter a 6-digit code emailed to this address before the secret opens. Team plan and above. Set this or passphrase, not both."
+        ),
+        note: z.string().max(4e3).optional().describe(
+          "A note for your own records, shown in the X-TKN console and never to the recipient. Stored unencrypted, so never put the secret in it."
+        )
+      },
+      outputSchema: {
+        link: z.string().describe("The one-time link for the recipient."),
+        code: z.string().describe("Pass this to check_status or revoke_secret."),
+        expiresAt: z.string().nullable(),
+        recipientAuth: z.enum(["passphrase", "email"]).nullable()
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    (args) => run(connection, async (client) => created(await createSecret(client, args)))
+  );
+  server.registerTool(
+    "check_status",
+    {
+      title: "Check a secret link",
+      description: "Whether a secret link is still waiting, has been opened, expired, or was revoked. Never returns the secret. Each call is one metered operation, and a sandbox has 100 in all, so call this no more often than every 30 seconds.",
+      inputSchema: { code },
+      outputSchema: statusShape,
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    ({ code: code2 }) => run(connection, async (client) => status(await checkStatus(client, code2)))
+  );
+  server.registerTool(
+    "revoke_secret",
+    {
+      title: "Revoke a secret link",
+      description: "Cancel a secret link so it can no longer be opened. Permanent, and immediate. A secret that was already opened stays opened: revoking cannot take it back from the recipient.",
+      inputSchema: { code },
+      outputSchema: statusShape,
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    ({ code: code2 }) => run(connection, async (client) => status(await revokeSecret(client, code2)))
+  );
+  return server;
+}
+async function run(connection, work) {
+  const called = await connection.call(work);
+  const result = called.ok ? called.value : { content: [{ type: "text", text: describeError(called.error, called.origin) }], isError: true };
+  if (called.notes.length === 0) return result;
+  return { ...result, content: [...result.content, { type: "text", text: called.notes.join("\n") }] };
+}
+function created(secret) {
+  const lines = [
+    `One-time link: ${secret.link}`,
+    `It opens once, then stops working. Expires: ${secret.expiresAt ?? "on the plan default"}.`
+  ];
+  if (secret.recipientAuth === "passphrase") {
+    lines.push("The recipient will be asked for the passphrase. Send it by a different channel than the link.");
+  } else if (secret.recipientAuth === "email") {
+    lines.push("The recipient will be emailed a 6-digit code to enter before it opens.");
+  }
+  lines.push(`Code for check_status and revoke_secret: ${secret.code}`);
+  return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: { ...secret } };
+}
+var STATUS_TEXT = {
+  waiting: "Waiting: not opened yet.",
+  opened: "Opened: the recipient has it, and the link no longer works.",
+  expired: "Expired before anyone opened it.",
+  revoked: "Revoked before anyone opened it."
+};
+function status(secret) {
+  const lines = [STATUS_TEXT[secret.status]];
+  if (secret.openedAt) lines.push(`Opened at ${secret.openedAt}.`);
+  if (secret.status === "waiting" && secret.expiresAt) lines.push(`Expires at ${secret.expiresAt}.`);
+  return { content: [{ type: "text", text: lines.join(" ") }], structuredContent: { ...secret } };
+}
+
+// src/index.ts
+async function main(argv) {
+  if (argv.includes("--version")) {
+    process.stdout.write(`${VERSION}
+`);
+    return;
+  }
+  if (!apiKeyFrom(process.env)) console.error(sandboxStartupMessage(sandboxCachePath(process.env)));
+  const server = createXtknMcpServer({ connection: connectionFrom(process.env) });
+  await server.connect(new StdioServerTransport());
+}
+main(process.argv.slice(2)).catch((err) => {
+  console.error("x-tkn-mcp failed to start:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@fennecstudio/x-tkn-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.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": [
+    "mcp",
+    "model-context-protocol",
+    "x-tkn",
+    "secret",
+    "one-time",
+    "agent"
+  ],
+  "homepage": "https://x-tkn.com",
+  "license": "ISC",
+  "author": "Fennec Studio",
+  "type": "module",
+  "bin": {
+    "x-tkn-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "vendor": "node ../js/scripts/vendor-crypto.mjs",
+    "build": "npm run vendor && node scripts/build.mjs",
+    "typecheck": "npm run vendor && tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "deploy": "npm publish",
+    "test": "npm run vendor && vitest run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  },
+  "packageManager": "pnpm@10.34.5"
+}