Greasemonkey Manual:Environment

Greasemonkey Manual
Using Greasemonkey
Installing Scripts
Monkey Menu
Getting Help
User Script Authoring
Editing
Environment
API

Why a Special Environment?

When Greasemonkey executes a user script it does so in a special sandbox environment. Greasemonkey takes advantage of a Firefox feature called XPCNativeWrappers to insulate the user script from the content web page, which it references.

Although this makes it more difficult, or impossible, to do certain things in your script, it is a necessary evil. Earlier versions of Greasemonkey had no such sandbox, and as a result, security holes were uncovered.

Greasemonkey provides certain enhanced APIs to the user script, so that it may accomplish things that a regular web page's javascript cannot. This useful feature has enabled some of the most popular scripts. Unfortunately, when abused, these powerful features can create serious problems. No exploits were ever uncovered in the wild, but the potential was too great, so the sandbox environment was created.

Luckily, for almost all the difficulties that the sandbox environment provides, there are ways to still accomplish the desired goal. The article Avoid Common Pitfalls in Greasemonkey does a wonderful job explaining what the most common snags are, and for each one explains the way to work around the problem. It is essential reading for any script author.

Finally, of note is the unsafeWindow object present in the sandbox. As the name implies, use of this object is unsafe! This is the raw, un-sandboxed "window" of the content page. Certain limited tasks can only be accomplished by referencing this raw window directly, but be warned! Javascript is a complicated and intricate language, even the most basic operations can be redefined by the content page to perform other actions. The sandbox environment is provided for your safety, and the safety of any user of your script. If at all possible, use of unsafeWindow should be avoided.

Control Flow

Sample control flow chart

Namespace
Privileged								Protected											Restricted
Chrome		→		Greasemonkey		→		new XPCNativeWrapper		→	new Sandbox			→	User Script 1	→
									↓								↓
									↓									→	Web Page A
									↓								↑
										→	new Sandbox			→	User Script 2	→
									↓
										→	new Sandbox			→	User Script 3		→		Web Page B
									↓
										→	new Sandbox			→	User Script 4		→		Web Page C
									↓
										→	...

What's Missing?

Depending on your usage, the special Greasemonkey environment may seem perfectly normal, or excessively limiting.

The Greasemonkey environment is a vanilla XPCNativeWrapper of the content window, with only certain extra bits added in to emulate a normal environment, or changed. Specifically:

• Keeping in mind the above Control Flow, Greasemonkey is unable to share script scope between two separate user scripts of the same namespace defined in the metadata block. Perhaps in the future this will be remedied. However it still can be useful for XML document namespace assignment, identification on userscripts.org and of course ensuring that scripts of identical names don't overwrite each other when installed or updated.
• window is an XPCNativeWrapper of the content window.
• document is the document object of the XPCNativeWrapper window object.
• XPathResult is added so that document.evaluate() works.
• Unless the @unwrap metadata imperative is present in the user script header, the entire script is wrapped inside an anonymous function, to guarantee the script's identifiers do not collide with identifiers present in the Mozilla javascript sandbox, resulting in confusing breakage. This function wrapper captures any function definitions and var variable declarations you make (e g var i = 5;) into the function's local scope. Declarations you make without var will however end up on the script's this object, which in Greasemonkey is the global object, contrary to in the normal browser object model, where the window object fills this function. In effect, after i = 5;, the values of window['i'] and window.i remain undefined, whereas this['i'] and this.i will be 5. See also: Global_object
• In order to access variables on the page, you need to use the unsafeWindow object. To use values defined in your script, simply reference them by their names.

Since Mozilla provides a rich environment, there are a wide variety of things that have not been imported from the general content scope into the Greasemonkey sandbox. Including, but not limited to:

• document.createTreeWalker
• SOAPCall

The more esoteric the method, the less likely that it has been included in the Greasemonkey sandbox.

See also

• Wikipedia: Sandbox
• Security
• Avoid Common Pitfalls in Greasemonkey