posterly-mcp-server 0.43.8 → 0.45.0

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);
+        }
+    }
+}

package/dist/lib/tool-registry.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Pure, dependency-free helpers over the MCP tool registry
+ * (mcp-server/tool-registry.json). Shared by BOTH surfaces:
+ *   - the npm stdio package (mcp-server/src/index.ts, alias-transport.ts)
+ *   - the hosted endpoint (lib/mcp/tool-registry.ts re-exports these with the
+ *     registry bound)
+ *
+ * This module never imports the JSON itself: each surface loads the registry
+ * its own way (createRequire on stdio, a static JSON import on hosted) and
+ * passes it in. Keep it free of Node, Next, and zod imports so it compiles
+ * unchanged under both the package tsconfig and the app tsconfig.
+ */
+export type ToolsetName = string;
+export type ConfirmLevel = 'none' | 'confirm' | 'preview';
+export type ToolSurface = 'hosted' | 'stdio';
+export type ModeSelector = 'view' | 'action' | 'type' | 'params';
+export type ExceptionCategory = 'money' | 'secret' | 'signup' | 'publishing' | 'ai_generation' | 'feedback' | 'connect' | 'single_action' | 'session' | 'dispatcher' | 'report';
+export interface ModeParamSpec {
+    type?: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    required?: boolean;
+    default?: unknown;
+    min?: number;
+    max?: number;
+    enum?: Array<string | number>;
+    /** Keep an explicit null (for example workspace_id: null clears a webhook's workspace). */
+    nullable?: boolean;
+}
+/** One view (read) or action (write) inside a multi-mode tool. */
+export interface ToolModeEntry {
+    label: string;
+    destructive?: boolean;
+    idempotent?: boolean;
+    openWorld?: boolean;
+    confirm?: ConfirmLevel;
+    /** Preview actions whose confirm may be used once only (public writes). */
+    nonce?: boolean;
+    /** When present, the only params this mode accepts (besides the selector, confirm, preview_id). */
+    params?: Record<string, ModeParamSpec>;
+    /**
+     * Param-driven tools (selector "params") only: this mode is chosen when any
+     * of these params is present. The one mode without `when` is the default.
+     */
+    when?: string[];
+}
+export interface ToolRegistryTool {
+    set: ToolsetName;
+    label: string;
+    /** Surfaces that register this tool. Defaults to both. */
+    surfaces?: ToolSurface[];
+    exception?: {
+        category: ExceptionCategory;
+        reason: string;
+    };
+    /** Single-mode tools carry their hints here; multi-mode tools derive them from views/actions. */
+    readOnly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    openWorld?: boolean;
+    confirm?: ConfirmLevel;
+    /**
+     * How a multi-mode tool picks its mode: an enum param (view/action/type), or
+     * "params" when the mode follows from which params are present (for example
+     * update_post with status vs content fields). Param-driven modes are still
+     * recorded as views/actions so the action count is derived from the registry.
+     */
+    selector?: ModeSelector;
+    /** Default view/action when the selector param is omitted. */
+    defaultMode?: string;
+    views?: Record<string, ToolModeEntry>;
+    actions?: Record<string, ToolModeEntry>;
+}
+export interface ToolRegistryAlias {
+    target: string;
+    /** Params forced onto the translated call (inject wins over caller args). */
+    inject?: Record<string, unknown>;
+    /** Old param name -> new param name. */
+    rename?: Record<string, string>;
+    /** Accept confirm:true without preview_id until sunset (per call, never stored on shared context). */
+    legacyConfirm?: boolean;
+    /**
+     * Param-driven targets (selector "params") only: the mode the old tool
+     * always ran in, so for example get_comment without comment_id is still
+     * rejected instead of silently listing every comment.
+     */
+    mode?: string;
+    added: string;
+    sunset: string;
+}
+export interface ToolRegistry {
+    $comment?: string;
+    version: number;
+    designRules: 'off' | 'on';
+    budgets: {
+        maxTotal: number;
+        maxCore: number;
+    };
+    sunset: string | null;
+    toolsets: Record<ToolsetName, {
+        label: string;
+        description: string;
+        alwaysOn?: boolean;
+        surfaces?: ToolSurface[];
+    }>;
+    tools: Record<string, ToolRegistryTool>;
+    aliases: Record<string, ToolRegistryAlias>;
+}
+export interface ResolvedAlias extends ToolRegistryAlias {
+    name: string;
+}
+/** The alias entry for `name`, or null when `name` is not an alias. */
+export declare function resolveAlias(registry: ToolRegistry, name: string): ResolvedAlias | null;
+/**
+ * Translates an alias call's arguments into the target tool's arguments.
+ * Always returns a fresh object (never mutates the caller's args): renames
+ * first, then injected params, which win over anything the caller passed.
+ */
+export declare function translateArgs(alias: ToolRegistryAlias, args: unknown): Record<string, unknown>;
+export type ValidateModeResult = {
+    ok: true;
+    mode: string | null;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The mode a param-driven tool (selector "params") runs in for these args:
+ * the first mode whose `when` params are present, otherwise the tool's
+ * default mode (the one without `when`). Undefined for other tools.
+ */
+export declare function detectParamsMode(tool: ToolRegistryTool, args: unknown): string | undefined;
+/**
+ * Validates and normalises a call's arguments against the registry's per-mode
+ * rules, BEFORE any request is made. It is the normaliser on both surfaces
+ * (the hosted endpoint has no zod), so a preview call and its confirm call
+ * hash identically: numeric strings become numbers, defaults are applied, and
+ * params outside the selected mode are rejected with a plain error.
+ *
+ * `explicitMode` forces a mode for param-driven tools (selector "params"), for
+ * example an alias of the old get_comment tool always runs in the comment
+ * mode. Without it, a param-driven tool's mode is detected from which params
+ * are present (see detectParamsMode).
+ *
+ * Tools without views/actions, and modes without a `params` spec, pass
+ * through unchanged (a fresh copy).
+ */
+export declare function validateMode(registry: ToolRegistry, toolName: string, args: unknown, explicitMode?: string): ValidateModeResult;
+/**
+ * The canonical form of a call's arguments for hashing: `confirm` and
+ * `preview_id` removed, undefined dropped, object keys sorted recursively,
+ * arrays kept in order. Pass args AFTER validateMode so defaults and number
+ * coercion are already applied.
+ */
+export declare function canonicalArgs(args: unknown): Record<string, unknown>;
+export interface DeprecationInfo {
+    old: string;
+    new: string;
+    action: string | null;
+    sunset: string;
+}
+/**
+ * The note appended (as a final text content item, never touching content[0])
+ * to every alias call's result, plus the matching _meta payload. `action` in
+ * the payload is the injected view/action/type value (null when none).
+ */
+export declare function deprecationNote(alias: ResolvedAlias): {
+    text: string;
+    meta: DeprecationInfo;
+};
+export declare const DEPRECATION_META_KEY = "posterly/deprecation";
+export interface ParsedToolsets {
+    /** Enabled set names, or every set when "all" (the default). */
+    enabled: ToolsetName[];
+    /** Requested names that are not known sets (ignored). */
+    unknown: string[];
+    /** True when every set is enabled. */
+    all: boolean;
+}
+/**
+ * Parses a toolset selection such as "core,inbox" or "all". Empty, missing,
+ * or all-unknown input means every set (nobody loses tools by mistake).
+ * With a surface, sets not available on it (for example signup, stdio only,
+ * on the hosted endpoint) are treated as unknown.
+ */
+export declare function parseToolsets(registry: ToolRegistry, value: string | null | undefined, surface?: ToolSurface): ParsedToolsets;
+/**
+ * Names of the canonical tools visible on `surface` for the enabled sets.
+ * Aliases are never listed. Sets marked alwaysOn (signup on stdio) are always
+ * visible. Surfaces keep their own registration order by filtering with this.
+ */
+export declare function visibleTools(registry: ToolRegistry, sets: ToolsetName[], surface: ToolSurface): Set<string>;
+export interface DerivedAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/**
+ * Annotation hints derived from the registry: a multi-action tool is
+ * destructive if any action is, idempotent only if all are, openWorld if any
+ * is; multi-view reads are readOnly + idempotent, openWorld if any view is.
+ */
+export declare function deriveAnnotations(tool: ToolRegistryTool): DerivedAnnotations;
+/** Actions (sub tools) a tool counts for: its views/actions, otherwise 1. */
+export declare function countActions(tool: ToolRegistryTool): number;
+export interface ToolListingAction {
+    key: string;
+    label: string;
+}
+export interface ToolListingTool {
+    name: string;
+    label: string;
+    /** The view/action/type param name, or null for param-driven or single-mode tools. */
+    selector: string | null;
+    /** Views/actions (the "sub tools") with plain-English labels; empty for single-mode tools. */
+    actions: ToolListingAction[];
+}
+export interface ToolListingSet {
+    set: ToolsetName;
+    label: string;
+    description: string;
+    tools: ToolListingTool[];
+}
+/**
+ * Every canonical tool on `surface`, grouped by tool set in registry order,
+ * each with its views/actions and their labels. This is what every tool list
+ * in the docs, marketing pages, and server card renders from, so the "sub
+ * tools" inside a merged tool are always shown. Aliases are never listed.
+ */
+export declare function listToolsBySet(registry: ToolRegistry, surface: ToolSurface): ToolListingSet[];
+/**
+ * What a called name resolves to: the canonical tool plus the view/action it
+ * runs (for an alias), or the name itself. Used by /admin/mcp to show old
+ * names next to the tool they now reach, without any new telemetry column.
+ */
+export declare function resolveCalledTool(registry: ToolRegistry, calledName: string): {
+    called: string;
+    tool: string;
+    mode: string | null;
+    alias: boolean;
+};
+/**
+ * The initialize `instructions` text: which tool sets exist, that they are
+ * all on by default, how to load fewer, and how preview then confirm works.
+ */
+export declare function toolsetInstructions(registry: ToolRegistry, surface: ToolSurface): string;