signet_sign

Instructions

Implementation Reference

• packages/signet-mcp-tools/src/tools.ts:87-117 (handler)

  MCP tool handler for 'signet_sign'. Reads SIGNET_SECRET_KEY from env, validates required args (tool, signer_name), builds a SignetAction, and calls the core sign() function to produce a signed receipt JSON. This is the primary handler for the signet_sign MCP tool.

  case 'signet_sign': {
    const secretKey = process.env.SIGNET_SECRET_KEY;
    if (!secretKey) {
      return {
        content: [{ type: 'text', text: 'Error: SIGNET_SECRET_KEY environment variable is not set. Set it before starting the server.' }],
        isError: true,
      };
    }
    if (!args?.tool || !args?.signer_name) {
      return {
        content: [{ type: 'text', text: 'Error: tool and signer_name are required.' }],
        isError: true,
      };
    }
    const action: SignetAction = {
      tool: args.tool as string,
      params: args?.params ?? {},
      params_hash: '',
      target: (args?.target as string) ?? '',
      transport: 'mcp',
    };
    const receipt = sign(
      secretKey,
      action,
      args.signer_name as string,
      (args?.signer_owner as string) ?? '',
    );
    return {
      content: [{ type: 'text', text: JSON.stringify(receipt) }],
    };
  }

• packages/signet-mcp-tools/src/tools.ts:34-46 (registration)

  Tool registration for 'signet_sign' in the ListToolsRequestSchema handler. Defines name, description, and inputSchema with parameters: tool, params, signer_name, signer_owner, target.

  name: 'signet_sign',
  description: 'Create a Signet receipt for a tool call before execution. The secret key is read from the SIGNET_SECRET_KEY environment variable (never passed as an argument). Returns the full signed receipt JSON.',
  inputSchema: {
    type: 'object' as const,
    properties: {
      tool: { type: 'string', description: 'Name of the tool or action being attested, for example github_create_issue or file_write.' },
      params: { description: 'Exact JSON arguments to bind into the receipt. Changing this JSON later will change the params hash and invalidate verification expectations.' },
      signer_name: { type: 'string', description: 'Stable signer or agent name that will appear in the receipt, such as ci-agent or research-bot.' },
      signer_owner: { type: 'string', description: 'Optional human, team, or org that owns the signer identity.' },
      target: { type: 'string', description: 'Optional target URI for the system where the action will run, such as mcp://github.local.' },
    },
    required: ['tool', 'signer_name'],
  },

• packages/signet-core/src/index.ts:9-20 (schema)

  TypeScript interface for SignetAction, the data structure representing the action being signed. Used by the signet_sign handler to build the action payload.

  export interface SignetAction {
    tool: string;
    params: unknown;
    params_hash: string;
    target: string;
    transport: string;
    session?: string;
    call_id?: string;
    response_hash?: string;
    trace_id?: string;
    parent_receipt_id?: string;
  }

• packages/signet-core/src/index.ts:67-76 (helper)

  Core sign() function that wraps the WASM-based signing logic. Called by the signet_sign handler to produce the signed receipt.

  export function sign(
    secretKey: string,
    action: SignetAction,
    signerName: string,
    signerOwner: string,
  ): SignetReceipt {
    const actionJson = JSON.stringify(action);
    const receiptJson = wasm_sign(secretKey, actionJson, signerName, signerOwner);
    return JSON.parse(receiptJson);
  }

• bindings/signet-py/python/signet_auth/decorator.py:298-301 (handler)

  Python alias: 'signet_sign = signet_tool' — a decorator-based API for signing tool calls, provided as backward-compatible name in the Python bindings.

  signet_sign = signet_tool
  
  # Convenience aliases
  sign = signet_sign