posterly-mcp-server 0.44.0 → 0.45.0

package/dist/lib/alias-transport.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Transport wrapper that keeps renamed MCP tools working on the stdio package
+ * without registering the old names with McpServer (so they never appear in
+ * tools/list).
+ *
+ * Incoming: a tools/call whose name is an alias is rewritten BEFORE McpServer
+ * sees it: params.name becomes the target tool and params.arguments become
+ * the translated arguments, so the SDK validates them against the canonical
+ * schema. The request id is remembered with the alias details.
+ *
+ * Handlers read that per-request info through getCallInfo(extra.requestId):
+ * the called name (for the X-Posterly-Tool telemetry header) and whether the
+ * alias may still confirm in one step. Nothing is stored in the arguments.
+ *
+ * Outgoing: the response for that id gets the rename note APPENDED as a final
+ * text item (content[0] is never touched) plus _meta["posterly/deprecation"],
+ * and the remembered entry is deleted. A notifications/cancelled for that id
+ * also deletes it (the SDK sends no response for a cancelled request).
+ *
+ * Legacy input schemas: when a legacyValidator is given, an alias call's
+ * arguments are first checked against the OLD tool's exact input schema, so a
+ * call the old tool rejected gets the same SDK validation error text (and a
+ * call it accepted gets the same parsed arguments, defaults included) before
+ * translation. The npm package passes the old zod schemas here.
+ *
+ * Tool sets: every tool stays registered (so a call to any tool always
+ * works); when a visible set is given, only the outgoing tools/list result is
+ * filtered to it.
+ *
+ * Only the public Transport interface is used; no SDK private fields.
+ */
+import type { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage, MessageExtraInfo, RequestId } from '@modelcontextprotocol/sdk/types.js';
+import { type ResolvedAlias, type ToolRegistry } from './tool-registry.js';
+export interface AliasCallInfo {
+    /** The name the client called (the alias). */
+    calledName: string;
+    /** The canonical tool the call was routed to. */
+    target: string;
+    /** The alias may confirm with confirm:true alone until its sunset date. */
+    legacyConfirm: boolean;
+    alias: ResolvedAlias;
+}
+/**
+ * Checks an alias call's raw arguments against the old tool's input schema.
+ * Return null when the alias has no legacy schema (no check), the parsed
+ * arguments when they are valid, or the exact error text the old tool gave.
+ */
+export type LegacyAliasValidator = (aliasName: string, args: unknown) => {
+    ok: true;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+} | null;
+export declare class AliasTransport implements Transport {
+    private readonly inner;
+    private readonly registry;
+    private readonly visibleTools;
+    private readonly legacyValidator;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
+    private readonly calls;
+    /** In-flight tools/list request ids, so only their responses are filtered. */
+    private readonly listRequests;
+    /**
+     * @param visibleTools names to list in tools/list, or null to list every
+     *   registered tool unchanged (the default: every set).
+     */
+    constructor(inner: Transport, registry: ToolRegistry, visibleTools?: Set<string> | null, legacyValidator?: LegacyAliasValidator | null);
+    get sessionId(): string | undefined;
+    setProtocolVersion(version: string): void;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    /** Alias details for an in-flight tools/call, or undefined for a canonical call. */
+    getCallInfo(requestId: RequestId | undefined): AliasCallInfo | undefined;
+    send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+    private handleIncoming;
+    /** Answers an alias call directly with a plain isError result; send() appends the rename note. */
+    private respondWithError;
+    private filterToolsList;
+    private decorateResponse;
+}

package/dist/lib/alias-transport.js

@@ -0,0 +1,193 @@
+/**
+ * Transport wrapper that keeps renamed MCP tools working on the stdio package
+ * without registering the old names with McpServer (so they never appear in
+ * tools/list).
+ *
+ * Incoming: a tools/call whose name is an alias is rewritten BEFORE McpServer
+ * sees it: params.name becomes the target tool and params.arguments become
+ * the translated arguments, so the SDK validates them against the canonical
+ * schema. The request id is remembered with the alias details.
+ *
+ * Handlers read that per-request info through getCallInfo(extra.requestId):
+ * the called name (for the X-Posterly-Tool telemetry header) and whether the
+ * alias may still confirm in one step. Nothing is stored in the arguments.
+ *
+ * Outgoing: the response for that id gets the rename note APPENDED as a final
+ * text item (content[0] is never touched) plus _meta["posterly/deprecation"],
+ * and the remembered entry is deleted. A notifications/cancelled for that id
+ * also deletes it (the SDK sends no response for a cancelled request).
+ *
+ * Legacy input schemas: when a legacyValidator is given, an alias call's
+ * arguments are first checked against the OLD tool's exact input schema, so a
+ * call the old tool rejected gets the same SDK validation error text (and a
+ * call it accepted gets the same parsed arguments, defaults included) before
+ * translation. The npm package passes the old zod schemas here.
+ *
+ * Tool sets: every tool stays registered (so a call to any tool always
+ * works); when a visible set is given, only the outgoing tools/list result is
+ * filtered to it.
+ *
+ * Only the public Transport interface is used; no SDK private fields.
+ */
+import { DEPRECATION_META_KEY, deprecationNote, resolveAlias, translateArgs, validateMode, } from './tool-registry.js';
+function requestKey(id) {
+    return `${typeof id}:${String(id)}`;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export class AliasTransport {
+    inner;
+    registry;
+    visibleTools;
+    legacyValidator;
+    onclose;
+    onerror;
+    onmessage;
+    calls = new Map();
+    /** In-flight tools/list request ids, so only their responses are filtered. */
+    listRequests = new Set();
+    /**
+     * @param visibleTools names to list in tools/list, or null to list every
+     *   registered tool unchanged (the default: every set).
+     */
+    constructor(inner, registry, visibleTools = null, legacyValidator = null) {
+        this.inner = inner;
+        this.registry = registry;
+        this.visibleTools = visibleTools;
+        this.legacyValidator = legacyValidator;
+        inner.onmessage = (message, extra) => this.handleIncoming(message, extra);
+        inner.onclose = () => this.onclose?.();
+        inner.onerror = (error) => this.onerror?.(error);
+    }
+    get sessionId() {
+        return this.inner.sessionId;
+    }
+    setProtocolVersion(version) {
+        this.inner.setProtocolVersion?.(version);
+    }
+    start() {
+        return this.inner.start();
+    }
+    close() {
+        this.calls.clear();
+        this.listRequests.clear();
+        return this.inner.close();
+    }
+    /** Alias details for an in-flight tools/call, or undefined for a canonical call. */
+    getCallInfo(requestId) {
+        if (requestId === undefined || requestId === null)
+            return undefined;
+        return this.calls.get(requestKey(requestId));
+    }
+    async send(message, options) {
+        const outgoing = this.filterToolsList(this.decorateResponse(message));
+        return this.inner.send(outgoing, options);
+    }
+    handleIncoming(message, extra) {
+        const request = message;
+        if (request.method === 'notifications/cancelled') {
+            const cancelled = isObject(request.params) ? request.params.requestId : undefined;
+            if (typeof cancelled === 'string' || typeof cancelled === 'number') {
+                this.calls.delete(requestKey(cancelled));
+                this.listRequests.delete(requestKey(cancelled));
+            }
+            this.onmessage?.(message, extra);
+            return;
+        }
+        if (request.method === 'tools/list' && this.visibleTools && request.id !== undefined && request.id !== null) {
+            this.listRequests.add(requestKey(request.id));
+            this.onmessage?.(message, extra);
+            return;
+        }
+        if (request.method !== 'tools/call' || request.id === undefined || request.id === null || !isObject(request.params)) {
+            this.onmessage?.(message, extra);
+            return;
+        }
+        const name = request.params.name;
+        const alias = typeof name === 'string' ? resolveAlias(this.registry, name) : null;
+        if (!alias) {
+            this.onmessage?.(message, extra);
+            return;
+        }
+        const info = {
+            calledName: alias.name,
+            target: alias.target,
+            legacyConfirm: alias.legacyConfirm === true,
+            alias,
+        };
+        this.calls.set(requestKey(request.id), info);
+        let callerArgs = request.params.arguments;
+        const legacy = this.legacyValidator ? this.legacyValidator(alias.name, callerArgs) : null;
+        if (legacy && !legacy.ok) {
+            this.respondWithError(request.id, legacy.message);
+            return;
+        }
+        if (legacy?.ok)
+            callerArgs = legacy.args;
+        // alias.mode pins a param-driven target to the old tool's mode.
+        const validated = validateMode(this.registry, alias.target, translateArgs(alias, callerArgs), alias.mode);
+        if (!validated.ok) {
+            // A plain error before any request, same as the hosted endpoint; the
+            // rename note is still appended by send() so the caller learns the new
+            // name either way.
+            this.respondWithError(request.id, validated.error);
+            return;
+        }
+        const rewritten = {
+            ...message,
+            params: { ...request.params, name: alias.target, arguments: validated.args },
+        };
+        this.onmessage?.(rewritten, extra);
+    }
+    /** Answers an alias call directly with a plain isError result; send() appends the rename note. */
+    respondWithError(id, text) {
+        void this.send({
+            jsonrpc: '2.0',
+            id,
+            result: { content: [{ type: 'text', text }], isError: true },
+        }).catch((error) => this.onerror?.(error instanceof Error ? error : new Error(String(error))));
+    }
+    filterToolsList(message) {
+        const response = message;
+        if (!this.visibleTools || response.method !== undefined || response.id === undefined || response.id === null)
+            return message;
+        const key = requestKey(response.id);
+        if (!this.listRequests.has(key))
+            return message;
+        this.listRequests.delete(key);
+        if (!isObject(response.result) || !Array.isArray(response.result.tools))
+            return message;
+        const visible = this.visibleTools;
+        const filtered = {
+            ...message,
+            result: {
+                ...response.result,
+                tools: response.result.tools.filter((tool) => typeof tool?.name === 'string' && visible.has(tool.name)),
+            },
+        };
+        return filtered;
+    }
+    decorateResponse(message) {
+        const response = message;
+        if (response.method !== undefined || response.id === undefined || response.id === null)
+            return message;
+        const key = requestKey(response.id);
+        const info = this.calls.get(key);
+        if (!info)
+            return message;
+        this.calls.delete(key);
+        if (!isObject(response.result) || !Array.isArray(response.result.content))
+            return message;
+        const note = deprecationNote(info.alias);
+        const decorated = {
+            ...message,
+            result: {
+                ...response.result,
+                content: [...response.result.content, { type: 'text', text: note.text }],
+                _meta: { ...(isObject(response.result._meta) ? response.result._meta : {}), [DEPRECATION_META_KEY]: note.meta },
+            },
+        };
+        return decorated;
+    }
+}

package/dist/lib/api-client.d.ts

@@ -1,3 +1,14 @@
+export declare function setMcpClientNameResolver(resolver: () => string | undefined): void;
+/**
+ * HTTP header values must be printable Latin-1 with no control characters;
+ * Node's fetch throws (not returns an error, THROWS) on a header value
+ * containing anything else, so an MCP client reporting a non-ASCII name
+ * (e.g. "通义灵码") or one with an en/em dash would otherwise break every
+ * single tool call. Strips anything outside printable ASCII rather than
+ * encoding it, since this is just a display label, not data that needs to
+ * round-trip losslessly.
+ */
+export declare function sanitizeClientHeaderValue(value: string): string;
 export interface Account {
     id: string;
     platform: string;
@@ -1049,6 +1060,13 @@ export declare class PosterlyClient {
     constructor(apiKey?: string, baseUrl?: string);
     hasApiKey(): boolean;
     getBaseUrl(): string;
+    /**
+     * Runs `fn` with a fresh per-call tool name/id scoped via AsyncLocalStorage,
+     * so any request() calls made inside it (directly or nested) are tagged
+     * with X-Posterly-Tool / X-Posterly-Tool-Call. Called once per tool
+     * invocation from index.ts's server.tool() handlers.
+     */
+    runToolCall<T>(toolName: string, fn: () => Promise<T>): Promise<T>;
     probeWhoami(timeoutMs?: number): Promise<{
         ok: boolean;
         status?: number;

package/dist/lib/api-client.js

@@ -1,5 +1,41 @@
 import { readFile } from 'fs/promises';
 import { resolve } from 'path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+/**
+ * Scopes the current tool name/call id to the async execution of a single
+ * tool call, so request() can tag its headers without a mutable "current
+ * tool" field on the shared PosterlyClient singleton (index.ts registers one
+ * client instance for every tool). AsyncLocalStorage keeps overlapping calls
+ * from clobbering each other's context if the stdio transport ever
+ * dispatches tool calls concurrently.
+ */
+const toolCallStorage = new AsyncLocalStorage();
+/**
+ * Resolves the connected MCP client's name (e.g. "claude-ai", "chatgpt"), set
+ * once by index.ts after the server is constructed. A resolver function
+ * rather than a static value because the SDK only learns the client's
+ * identity once the initialize handshake completes, which happens after this
+ * module is first loaded; reading through the resolver on every request
+ * always gets the current value instead of whatever was available at import
+ * time (undefined).
+ */
+let clientNameResolver = null;
+export function setMcpClientNameResolver(resolver) {
+    clientNameResolver = resolver;
+}
+/**
+ * HTTP header values must be printable Latin-1 with no control characters;
+ * Node's fetch throws (not returns an error, THROWS) on a header value
+ * containing anything else, so an MCP client reporting a non-ASCII name
+ * (e.g. "通义灵码") or one with an en/em dash would otherwise break every
+ * single tool call. Strips anything outside printable ASCII rather than
+ * encoding it, since this is just a display label, not data that needs to
+ * round-trip losslessly.
+ */
+export function sanitizeClientHeaderValue(value) {
+    return value.replace(/[^\x20-\x7e]/g, '').trim().slice(0, 200);
+}
 export class PosterlyClient {
     baseUrl;
     apiKey;
@@ -16,6 +52,15 @@ export class PosterlyClient {
     getBaseUrl() {
         return this.baseUrl;
     }
+    /**
+     * Runs `fn` with a fresh per-call tool name/id scoped via AsyncLocalStorage,
+     * so any request() calls made inside it (directly or nested) are tagged
+     * with X-Posterly-Tool / X-Posterly-Tool-Call. Called once per tool
+     * invocation from index.ts's server.tool() handlers.
+     */
+    async runToolCall(toolName, fn) {
+        return toolCallStorage.run({ toolName, toolCallId: randomUUID() }, fn);
+    }
     async probeWhoami(timeoutMs = 2500) {
         const startedAt = Date.now();
         if (!this.apiKey) {
@@ -78,6 +123,16 @@ export class PosterlyClient {
             Authorization: `Bearer ${this.apiKey}`,
             'X-Posterly-Source': 'mcp_stdio',
         };
+        const toolCall = toolCallStorage.getStore();
+        if (toolCall) {
+            headers['X-Posterly-Tool'] = toolCall.toolName;
+            headers['X-Posterly-Tool-Call'] = toolCall.toolCallId;
+        }
+        const clientName = clientNameResolver?.();
+        const clientLabel = clientName ? sanitizeClientHeaderValue(clientName) : '';
+        if (clientLabel) {
+            headers['X-Posterly-Client'] = clientLabel;
+        }
         const init = { method, headers };
         if (body instanceof FormData) {
             init.body = body;

package/dist/lib/preview-token-core.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Preview-then-confirm tokens for MCP write actions, shared by both surfaces.
+ * Depends on node:crypto only.
+ *
+ * Format: pv1.<exp>.<nonce>.<mac>
+ *   exp   unix seconds when the preview stops being confirmable
+ *   nonce random, base64url; also the one-time-use key for nonce actions
+ *   mac   base64url HMAC-SHA256(key,
+ *           "posterly-mcp-preview-v1|" + exp + "|" + nonce + "|" + userId
+ *           + "|" + tool + "|" + action + "|" + canonicalJson(args))
+ *
+ * The token binds the preview to one user, one tool, one action, and the
+ * exact (normalised) arguments, so a confirm call with different args, from a
+ * different user, or after expiry is refused. It is UX protection that a
+ * human saw what will change, not authorization: REST scopes and ownership
+ * checks still decide what is allowed.
+ *
+ * Callers own the key (hosted: derived from a server secret; stdio: random
+ * per process) and the one-time-use store (hosted: Redis; stdio: memory).
+ */
+export declare const PREVIEW_TOKEN_VERSION = "pv1";
+export interface PreviewBinding {
+    userId: string;
+    tool: string;
+    action: string;
+    /** Arguments AFTER validation/normalisation (defaults applied, numbers coerced). */
+    args: unknown;
+}
+export type VerifyPreviewResult = {
+    ok: true;
+    exp: number;
+    nonce: string;
+    remainingSeconds: number;
+} | {
+    ok: false;
+    reason: 'malformed' | 'expired' | 'mismatch';
+};
+/**
+ * Canonical JSON of a call's arguments: `confirm` and `preview_id` removed
+ * (top level), undefined dropped, keys sorted recursively, arrays kept in
+ * order, no whitespace. Same rules as canonicalArgs in tool-registry.ts.
+ */
+export declare function canonicalJson(args: unknown): string;
+/** Derives the MAC key from a server secret with a domain prefix, so the raw secret is never the key. */
+export declare function derivePreviewKey(secret: string | Buffer, domain?: string): Buffer;
+export declare function createPreviewToken(key: Buffer, binding: PreviewBinding, options: {
+    ttlSeconds: number;
+    nowMs?: number;
+    nonce?: string;
+}): string;
+export declare function parsePreviewToken(token: unknown): {
+    exp: number;
+    nonce: string;
+    mac: string;
+} | null;
+export declare function verifyPreviewToken(key: Buffer, token: unknown, binding: PreviewBinding, options?: {
+    nowMs?: number;
+}): VerifyPreviewResult;
+/** Stable fingerprint of a token for one-time-use bookkeeping (never store the raw token). */
+export declare function previewTokenFingerprint(token: string): string;
+/** Plain-language refusal for each verification failure. */
+export declare function previewFailureMessage(reason: 'malformed' | 'expired' | 'mismatch' | 'used' | 'missing' | 'unavailable'): string;

package/dist/lib/preview-token-core.js

@@ -0,0 +1,131 @@
+/**
+ * Preview-then-confirm tokens for MCP write actions, shared by both surfaces.
+ * Depends on node:crypto only.
+ *
+ * Format: pv1.<exp>.<nonce>.<mac>
+ *   exp   unix seconds when the preview stops being confirmable
+ *   nonce random, base64url; also the one-time-use key for nonce actions
+ *   mac   base64url HMAC-SHA256(key,
+ *           "posterly-mcp-preview-v1|" + exp + "|" + nonce + "|" + userId
+ *           + "|" + tool + "|" + action + "|" + canonicalJson(args))
+ *
+ * The token binds the preview to one user, one tool, one action, and the
+ * exact (normalised) arguments, so a confirm call with different args, from a
+ * different user, or after expiry is refused. It is UX protection that a
+ * human saw what will change, not authorization: REST scopes and ownership
+ * checks still decide what is allowed.
+ *
+ * Callers own the key (hosted: derived from a server secret; stdio: random
+ * per process) and the one-time-use store (hosted: Redis; stdio: memory).
+ */
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+export const PREVIEW_TOKEN_VERSION = 'pv1';
+const MAC_DOMAIN = 'posterly-mcp-preview-v1';
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map((item) => (item === undefined ? null : sortKeysDeep(item)));
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const item = value[key];
+            if (item === undefined)
+                continue;
+            out[key] = sortKeysDeep(item);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Canonical JSON of a call's arguments: `confirm` and `preview_id` removed
+ * (top level), undefined dropped, keys sorted recursively, arrays kept in
+ * order, no whitespace. Same rules as canonicalArgs in tool-registry.ts.
+ */
+export function canonicalJson(args) {
+    const source = isPlainObject(args) ? args : {};
+    const stripped = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (key === 'confirm' || key === 'preview_id')
+            continue;
+        stripped[key] = value;
+    }
+    return JSON.stringify(sortKeysDeep(stripped));
+}
+/** Derives the MAC key from a server secret with a domain prefix, so the raw secret is never the key. */
+export function derivePreviewKey(secret, domain = 'posterly-mcp-preview-key-v1') {
+    return createHmac('sha256', secret).update(domain).digest();
+}
+function field(value) {
+    // Pipes separate fields; ids never contain them, but never let one shift a
+    // boundary. Percent is escaped first so the encoding is injective: a value
+    // that already contains "%7C" cannot collide with one that contains "|".
+    return value.replace(/%/g, '%25').replace(/\|/g, '%7C');
+}
+function computeMac(key, exp, nonce, binding) {
+    const payload = [
+        MAC_DOMAIN,
+        String(exp),
+        nonce,
+        field(binding.userId),
+        field(binding.tool),
+        field(binding.action),
+        canonicalJson(binding.args),
+    ].join('|');
+    return createHmac('sha256', key).update(payload).digest('base64url');
+}
+export function createPreviewToken(key, binding, options) {
+    const now = Math.floor((options.nowMs ?? Date.now()) / 1000);
+    const exp = now + Math.max(1, Math.floor(options.ttlSeconds));
+    const nonce = options.nonce ?? randomBytes(16).toString('base64url');
+    const mac = computeMac(key, exp, nonce, binding);
+    return `${PREVIEW_TOKEN_VERSION}.${exp}.${nonce}.${mac}`;
+}
+export function parsePreviewToken(token) {
+    if (typeof token !== 'string')
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 4 || parts[0] !== PREVIEW_TOKEN_VERSION)
+        return null;
+    const [, expRaw, nonce, mac] = parts;
+    if (!/^\d{1,12}$/.test(expRaw) || !/^[A-Za-z0-9_-]{8,64}$/.test(nonce) || !/^[A-Za-z0-9_-]{20,100}$/.test(mac))
+        return null;
+    return { exp: Number(expRaw), nonce, mac };
+}
+export function verifyPreviewToken(key, token, binding, options = {}) {
+    const parsed = parsePreviewToken(token);
+    if (!parsed)
+        return { ok: false, reason: 'malformed' };
+    const expected = Buffer.from(computeMac(key, parsed.exp, parsed.nonce, binding));
+    const actual = Buffer.from(parsed.mac);
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+        return { ok: false, reason: 'mismatch' };
+    }
+    const now = Math.floor((options.nowMs ?? Date.now()) / 1000);
+    if (parsed.exp <= now)
+        return { ok: false, reason: 'expired' };
+    return { ok: true, exp: parsed.exp, nonce: parsed.nonce, remainingSeconds: parsed.exp - now };
+}
+/** Stable fingerprint of a token for one-time-use bookkeeping (never store the raw token). */
+export function previewTokenFingerprint(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+/** Plain-language refusal for each verification failure. */
+export function previewFailureMessage(reason) {
+    switch (reason) {
+        case 'missing':
+            return 'confirm: true needs the preview_id from a preview call. Call once without confirm, show the preview to the user, then confirm with its preview_id.';
+        case 'expired':
+            return 'This preview expired, so nothing was changed. Call again without confirm to get a fresh preview.';
+        case 'mismatch':
+            return 'This preview does not match these arguments, so nothing was changed. Call again without confirm to get a fresh preview for exactly what should happen.';
+        case 'used':
+            return 'This preview was already used, so nothing was changed. Call again without confirm to get a fresh preview.';
+        case 'unavailable':
+            return 'posterly could not check this preview right now, so nothing was changed. Please retry in a moment.';
+        default:
+            return 'preview_id is not valid, so nothing was changed. Call again without confirm to get a fresh preview.';
+    }
+}

package/dist/lib/preview-token.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Stdio (npm package) preview tokens: a random key per process and an
+ * in-memory one-time-use set. A preview only survives as long as the local
+ * MCP process does, which matches how a local client uses it (preview and
+ * confirm happen in the same session). This is UX protection only: REST
+ * authorization on the posterly API is unchanged.
+ */
+import { type PreviewBinding, type VerifyPreviewResult } from './preview-token-core.js';
+export declare const STDIO_PREVIEW_TTL_SECONDS: number;
+export declare class StdioPreviewTokens {
+    private readonly ttlSeconds;
+    private readonly key;
+    private readonly used;
+    constructor(key?: Buffer, ttlSeconds?: number);
+    create(binding: PreviewBinding, nowMs?: number): string;
+    verify(token: unknown, binding: PreviewBinding, nowMs?: number): VerifyPreviewResult;
+    /**
+     * Marks a verified token as used. Returns false when it was already used
+     * (a second confirm with the same preview_id). Call only after verify().
+     */
+    claimOnce(token: string, expSeconds: number, nowMs?: number): boolean;
+    private sweep;
+}

package/dist/lib/preview-token.js

@@ -0,0 +1,44 @@
+/**
+ * Stdio (npm package) preview tokens: a random key per process and an
+ * in-memory one-time-use set. A preview only survives as long as the local
+ * MCP process does, which matches how a local client uses it (preview and
+ * confirm happen in the same session). This is UX protection only: REST
+ * authorization on the posterly API is unchanged.
+ */
+import { randomBytes } from 'node:crypto';
+import { createPreviewToken, previewTokenFingerprint, verifyPreviewToken, } from './preview-token-core.js';
+export const STDIO_PREVIEW_TTL_SECONDS = 10 * 60;
+export class StdioPreviewTokens {
+    ttlSeconds;
+    key;
+    used = new Map();
+    constructor(key = randomBytes(32), ttlSeconds = STDIO_PREVIEW_TTL_SECONDS) {
+        this.ttlSeconds = ttlSeconds;
+        this.key = key;
+    }
+    create(binding, nowMs) {
+        return createPreviewToken(this.key, binding, { ttlSeconds: this.ttlSeconds, nowMs });
+    }
+    verify(token, binding, nowMs) {
+        return verifyPreviewToken(this.key, token, binding, { nowMs });
+    }
+    /**
+     * Marks a verified token as used. Returns false when it was already used
+     * (a second confirm with the same preview_id). Call only after verify().
+     */
+    claimOnce(token, expSeconds, nowMs = Date.now()) {
+        this.sweep(nowMs);
+        const fingerprint = previewTokenFingerprint(token);
+        if (this.used.has(fingerprint))
+            return false;
+        this.used.set(fingerprint, expSeconds);
+        return true;
+    }
+    sweep(nowMs) {
+        const now = Math.floor(nowMs / 1000);
+        for (const [fingerprint, exp] of this.used) {
+            if (exp <= now)
+                this.used.delete(fingerprint);
+        }
+    }
+}