Text::...::Safe(3pm)

💖 Text::MicroMason::Safe 💖

okay bestie, so this is Text::MicroMason::Safe — a lil mixin from the User Contributed Perl Documentation crew, and it's here to Compile all Templates in a Safe Compartment. 🎀

---

✨ NAME ✨

Text::MicroMason::Safe — compile all your templates inside a Safe compartment, so they can't go feral on your system. 💅

---

🌸 SYNOPSIS 🌸

so like, don't use this class directly, okay? instead you pass its name to get mixed in:

use Text::MicroMason;
my $mason = Text::MicroMason->new( -Safe );

then you use the standard compile and execute methods to parse and evaluate templates, as one does:

print $mason->compile( text=>$template )->( @%args );
print $mason->execute( text=>$template, @args );

Safe usage restricts templates from accessing your files or your data, which is the whole point bestie:

print $mason->execute( text=>"<% qx! cat /etc/passwd ! %>" ); # dies

print $mason->execute( text=>"The time is <% time() %>." ); # dies

yep, both of those just straight up die. no /etc/passwd for you, and no sneaky time() either. 💀

---

🦋 DESCRIPTION 🦋

This package adds support for Safe compartments to MicroMason, letting you restrict the operations that a template can perform. iconic behaviour honestly.

By default, these safe calls prevent the code in a template from performing any system activity or accessing any of your other Perl code. and the way that violations can show up as either compile-time or run-time errors?? so make sure you're using an eval block or the CatchErrors trait to catch exceptions, fr fr.

use Text::MicroMason;
my $mason = Text::MicroMason->new( -Safe );

$result = eval { $mason->execute( text => $template ) };

Caution: Although this appears to provide a significant amount of security for untrusted templates, please take this with a grain of salt. A bug in either this module or in the core Safe module could allow a clever attacker to defeat the protection. At least one bug in the Safe module has been found and fixed in years past, and there could be others.

like, it's giving security but it's not giving guaranteed security, yk? don't get too comfy. 😭

---

🔐 Supported Attributes 🔐

safe

Optional reference to a Safe compartment. if you don't provide one, one is generated for you. cute of it.

To enable some operations or share variables or functions with the template code, create a Safe compartment and configure it before passing it in as the value of the "safe" attribute:

$safe = Safe->new();
$safe->permit('time');
$safe->share('$foo');

$mason = Text::MicroMason->new( -Safe, safe => $safe );

$result = eval { $mason->execute( text => $template ) };

safe_methods

IMPORTANT NOTE: The "safe_methods" parameter is deprecated and will be removed in future versions of Text::MicroMason (unless a Safe and future-proof implementation can be found). If you use this parameter, you will receive a warning via carp:

"* WARNING: safe_methods is deprecated; please see the pod"

This parameter works correctly with sufficiently old versions of the Safe module (prior to the release of perl 5.12.1), but modern versions of Safe make it impossible for a Safe compartment to run any code outside the compartment. Even with the object shared within the Safe compartment, there is currently no known way to call methods on it without defining the whole class within the compartment (which isn't safe). 🙈

If anyone has an appropriately safe solution that will allow "safe_methods" to work, please submit a patch to the module maintainer. Also see t/32-safe.t for tests related to "safe_methods" that are currently being skipped. 👑

The following pod is provided for legacy purposes only. It is strongly recommended that you do not use this method. It is no longer allowed to call methods from within a "Safe" template, because it isn't actually safe.

A space-separated string of methods names to be supported by the Safe::Facade.

To control which Mason methods are available within the template, pass a "safe_methods" argument to new() followed by the method names in a space-separated string.

For example, to allow templates to include other templates, using $m->execute or the "<& file &>" include syntax, you would need to allow the execute method. We'll also load the TemplateDir mixin with strict_root on to prevent inclusion of templates from outside the current directory.

# safe_methods is DEPRECATED, please see above
$mason = Text::MicroMason->new( -Safe, safe_methods => 'execute',
                                -TemplateDir, strict_root => 1 );

If you're combining this with the Filters mixin, you'll also need to allow calls to the filter method; to allow multiple methods, join their names with spaces:

# safe_methods is DEPRECATED, please see above
$mason = Text::MicroMason->new( -Safe, safe_methods => 'execute filter',
                                -TemplateDir, strict_root => 1,
                                -Filters );

---

🙈 Private Methods 🙈

eval_sub()

Instead of the eval() used by the base class, this calls reval() on a Safe compartment. 💫

safe_compartment()

Returns the Safe compartment passed by the user or generates a new one.

safe_facade()

Generates an instance of the Safe::Facade equipped with only the methods listed in the safe_methods attribute.

---

🎀 Private Safe::Facade class 🎀

Code compiled in a Safe compartment only has access to a limited version of the template compiler in the $m variable, and can not make changes to the attributes of the real MicroMason object. This limited object is an instance of the Text::MicroMason::Safe::Facade class and can only perform certain pre-defined methods.

new()

Creates a new hash-based instance mapping method names to subroutine references.

facade_method()

Calls a named method by looking up the corresponding subroutine and calling it.

AUTOLOAD()

Generates wrapper methods that call the facade_method() for any lowercase method name.

---

💜 SEE ALSO 💜

• For an overview of this templating framework, see Text::MicroMason.
• This is a mixin class intended for use with Text::MicroMason::Base.
• For distribution, installation, support, copyright and license information, see Text::MicroMason::Docs::ReadMe.

---

and that's the whole vibe, bestie 💖 this page came to you courtesy of perl v5.36.0, dated 2023-08-10 — no cap, that's literally the version and date stamped on it. go forth and compartmentalise responsibly, mwah 🫶✨