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

package/README.md

@@ -1,3 +1,130 @@
-# 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 and an X-TKN API key. Developer keys are free: sign up
+at [x-tkn.com](https://x-tkn.com) and create one in the account console.
+Sandbox keys (from `POST /accounts/sandbox`) cannot create secrets.
+
+**Claude Code**
+
+```bash
+claude mcp add x-tkn -e X_TKN_API_KEY=your-key -- npx -y @fennecstudio/x-tkn-mcp
+```
+
+**Claude Desktop, Cursor, Windsurf and other clients** take the same block in
+their MCP config file:
+
+```json
+{
+  "mcpServers": {
+    "x-tkn": {
+      "command": "npx",
+      "args": ["-y", "@fennecstudio/x-tkn-mcp"],
+      "env": { "X_TKN_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+Without a key the server still starts, and every tool call answers with how to
+get one.
+
+## 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.                          |
+| `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.
+
+### `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,921 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../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, 24 hours, and no
+   * `secret` tokens. {@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.
+   *
+   * @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/version.ts
+var VERSION = "1.0.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) {
+  return new XTkn({ apiKey: apiKeyFrom(env), headers: { "User-Agent": USER_AGENT } });
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// ../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 NO_KEY_MESSAGE = `No X-TKN API key. Set ${API_KEY_ENV_VARS[0]} in this MCP server's environment. Developer keys are free: sign up at ${SIGNUP_URL} and create one in the account console. Sandbox keys cannot create secrets.`;
+var SANDBOX_KEY_MESSAGE = `This is a sandbox key, and sandbox accounts cannot create secrets. Set ${API_KEY_ENV_VARS[0]} to a free Developer key instead: sign up at ${SIGNUP_URL} and create one in the account console.`;
+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) {
+  if (err instanceof XTknPaymentRequiredError) {
+    if (err.upgradeMethod === "claim") return SANDBOX_KEY_MESSAGE;
+    const plan = err.requiredPlan ? `the ${err.requiredPlan} plan` : "a paid plan";
+    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 accounts cannot create secrets")) {
+    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/server.ts
+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."
+].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({ 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."),
+        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(async () => 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.",
+      inputSchema: { code },
+      outputSchema: statusShape,
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    ({ code: code2 }) => run(async () => 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(async () => status(await revokeSecret(client, code2)))
+  );
+  return server;
+}
+async function run(work) {
+  try {
+    return await work();
+  } catch (err) {
+    return { content: [{ type: "text", text: describeError(err) }], isError: true };
+  }
+}
+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(NO_KEY_MESSAGE);
+  const server = createXtknMcpServer({ client: clientFrom(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.0.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"
+}