Template Functions - Anthony-Bible/password-exchange GitHub Wiki

Email Template Functions Documentation

This document describes the allowed template functions for email templates in the Password Exchange notification system.

Security Overview

The email template system uses a restricted set of template functions to prevent template injection attacks (OWASP A03:2021 – Injection). Only explicitly allowed functions can be used in email templates.

Template Security Features

  • Function Allowlist: Only predefined safe functions are permitted
  • Size Limits: Templates are limited to 10KB maximum
  • Nesting Limits: Maximum 50 levels of template nesting
  • Path Traversal Protection: Blocks attempts to access system files
  • Script Injection Prevention: Prevents JavaScript and other script injections
  • Dangerous Function Detection: Blocks functions like exec, system, call, etc.

Allowed Template Functions

String Manipulation Functions

Function Description Example Usage
upper Converts string to uppercase {{upper .RecipientName}}
lower Converts string to lowercase {{lower .SenderName}}
title Converts string to title case {{title .Message}}
trim Removes leading/trailing whitespace {{trim .Body}}
replace Replaces all occurrences of a substring {{replace .Body "old" "new"}}

HTML Security Functions

Function Description Example Usage
html Escapes HTML characters for safe display {{html .Message}}
js Escapes text for safe use in JavaScript {{js .RecipientName}}
url Escapes text for safe use in URLs {{url .PasswordExchangeURL}}

Formatting Functions

Function Description Example Usage
printf Formatted string printing {{printf "Hello %s" .RecipientName}}

Built-in Go Template Functions

The following Go template built-in functions are also allowed:

Function Description Example Usage
and Logical AND operation {{if and .Field1 .Field2}}
or Logical OR operation {{if or .Field1 .Field2}}
not Logical NOT operation {{if not .Field1}}
len Returns length of string/slice/map {{len .Message}}
index Returns element at index {{index .Array 0}}
print Print values {{print .Value}}
println Print values with newline {{println .Value}}

Template Control Structures

Structure Description Example Usage
if/else/end Conditional logic {{if .Message}}...{{else}}...{{end}}
range/end Iterate over collections {{range .Items}}...{{end}}
with/end Set context {{with .User}}...{{end}}
template Include other templates {{template "name" .}}
define/end Define template blocks {{define "name"}}...{{end}}
block/end Define default blocks {{block "name" .}}...{{end}}

Available Template Data

Email templates have access to the following data structure:

type NotificationTemplateData struct {
    Body    string  // Pre-formatted email body content
    Message string  // The encrypted message content (when available)
}

Template Examples

Basic Email Template

<!DOCTYPE html>
<html>
<head>
    <title>Password Exchange Notification</title>
</head>
<body>
    <h1>{{upper "Password Exchange"}}</h1>
    <p>{{html .Body}}</p>
    {{if .Message}}
        <div class="message">
            <strong>Message Preview:</strong>
            <p>{{html .Message}}</p>
        </div>
    {{end}}
</body>
</html>

Template with String Manipulation

<div class="notification">
    <h2>{{title "new secure message"}}</h2>
    <p>Message length: {{len .Message}} characters</p>
    <p>{{replace .Body "Password Exchange" "Secure Exchange"}}</p>
</div>

Template with Conditional Logic

{{if .Message}}
    <div class="preview">
        <h3>Message Preview</h3>
        <p>{{trim (html .Message)}}</p>
    </div>
{{else}}
    <p>No message preview available.</p>
{{end}}

Security Restrictions

Blocked Functions

The following types of functions are strictly prohibited:

  • System execution functions: exec, system, call
  • File system functions: readFile, writeFile, open
  • Network functions: httpGet, httpPost, fetch
  • Arbitrary code execution: eval, execute
  • Shell commands: sh, bash, cmd

Blocked Patterns

Templates cannot contain:

  • Path traversal attempts: ../, /etc/, /var/, etc.
  • Script injections: <script>, javascript:, onload=
  • System paths: C:\, %SYSTEMROOT%
  • Dangerous protocols: file://, ftp://

Size and Nesting Limits

  • Maximum template size: 10KB
  • Maximum nesting depth: 50 levels
  • Template validation is performed before parsing

Error Handling

Invalid templates will result in specific error messages:

  • "template too large" - Template exceeds 10KB limit
  • "dangerous function 'X' detected" - Blocked function usage
  • "undefined function 'X' detected" - Non-allowlisted function
  • "path traversal pattern detected" - Path traversal attempt
  • "script injection pattern detected" - Script injection attempt
  • "nesting too deep" - Exceeds 50-level nesting limit

Template Configuration

Templates can be configured in two ways:

  1. File-based: Specify a file path in configuration
  2. Inline: Provide template content directly in configuration

Both methods undergo the same security validation process.

Security Note: This restricted function set is designed to provide essential email templating capabilities while preventing template injection attacks. Additional functions should only be added after thorough security review.

⚠️ **GitHub.com Fallback** ⚠️