Generator Template Escaping for Non-Code Locations¶

Authors

Matt Cockayne

Date

02 April 2026

Status

APPROVED

Overview¶

A security audit identified that internal/generator/skeleton.go uses text/template to render scaffolded project files with user-provided data. Because text/template performs no automatic escaping, a malicious or accidental input value (e.g. a Slack channel name containing {{ . or backtick sequences) could cause template injection, producing corrupted output, information disclosure, or build failures in the generated project.

Template data must NOT be escaped where it appears in generated Go code (identifiers, types, import paths, struct field values) because escaping would cause compilation errors. The scope of this spec is strictly limited to non-code locations: string values in YAML/TOML configuration files, Markdown documentation, comments, and similar textual output.

Threat Model¶

Defence Strategy: Two Layers¶

Defence-in-depth requires both input validation and output escaping:

1. Input validation (Phase 1) — rejects values that are structurally dangerous (.., control characters, invalid Go identifiers, invalid hostnames). This is the primary line of defence: most injection vectors collapse if the input is constrained to a safe character class.
2. Output escaping (Phase 2) — context-aware escaping at each non-code template site, so that values passing validation (and future values whose constraints loosen) cannot produce malformed output.

Input validation alone is not sufficient (escaping constraints vary by output format; a valid Name in one context may still be problematic in another). Output escaping alone is not sufficient (escaping .. in path components requires context; input validation is cleaner).

Scope¶

In scope:

• All text/template rendered files in internal/generator/assets/skeleton/, skeleton-github/, and skeleton-gitlab/
• The two inline template strings: SkeletonGoMod and SkeletonConfig
• Identification of code vs non-code template locations
• Input validation rules for user-provided fields (Name, Description, Repo, Host, Org, Slack/Teams identifiers, EnvPrefix)
• Custom template function(s) for escaping non-code outputs
• Fuzz testing of escape functions

Out of scope:

• Jennifer-generated Go files (skeleton_root.go) — jennifer's Lit() function already handles Go string literal escaping. Note: EnvPrefix, SlackChannel, SlackTeam, TeamsChannel, TeamsTeam, TelemetryEndpoint, TelemetryOTelEndpoint currently flow only through jennifer (jen.Lit). If future changes route them through text templates, their escaping must be audited.
• Template rendering in non-generator contexts
• Post-generation validation of the scaffolded project (e.g. running go build as part of the generator)

Design Decisions¶

Custom template functions over html/template: Using html/template is unsuitable because it escapes for HTML contexts, not YAML/Markdown/TOML contexts. Custom functions give precise control over escaping per output format.

Opt-in escaping at call sites: Rather than globally escaping all fields (which would break code locations), each non-code template location explicitly pipes through an escape function. This makes the escaping intent visible and auditable.

Multiple escape functions by context: Different output formats need different escaping rules. YAML values need quoting, Markdown needs backtick/link escaping, and TOML string values need quote escaping. A single escape function would be either too aggressive or too lax.

No changes to jennifer-generated code: The skeleton_root.go file uses jen.Lit() which already handles Go string escaping. No additional escaping is needed there.

Validation rejects; escaping sanitises: Validation errors abort generation with an actionable message. Escape functions are pure and infallible — they never panic, never error, and always produce valid output for any input. Rejection belongs at the entry point; sanitisation belongs at the rendering layer.

NFC Unicode normalisation on string fields: All user-provided string fields are normalised to Unicode NFC form before validation and template rendering. This prevents homoglyph attacks and normalises away combining characters. Fields that must be ASCII (e.g. Name, Org, EnvPrefix) fail validation if they contain non-ASCII code points after normalisation.

Input Validation¶

Validation runs at the wizard/flag entry point in internal/generator/skeleton.go (via SkeletonOptions.ValidateOrPrompt and the equivalent manifest loading paths in regenerate.go). Validation errors abort generation with a clear message indicating which field failed and why.

Field Validation Rules¶

All validation uses the canonical forms in internal/generator/validate.go (new file). Error messages are structured using cockroachdb/errors with WithHint so the wizard can display actionable guidance.

Validation Timing¶

Validation runs:

1. After the interactive wizard collects each value (per-field, with immediate feedback).
2. When CLI flags are parsed (before any file is written).
3. When a generator.toml manifest is loaded for regenerate.

Validation is never deferred to template rendering time.

Public API¶

This feature is entirely internal to internal/generator/. No pkg/ API changes are required. No API stability implications.

Internal Implementation¶

User-Provided Data Fields¶

The following fields originate from user input (interactive wizard or CLI flags) and flow through template rendering:

Template Location Audit¶

Non-Code Locations (Require Escaping)¶

Code Locations (Must NOT Be Escaped)¶

Escaping Strategy¶

Dual-Use Fields¶

Several fields (Name, ModulePath) appear in both code and non-code contexts within the same file. For these cases, the template must use the raw field in code locations and the escaped variant in non-code locations.

The recommended approach is to register custom template functions and use piped escaping only at non-code call sites:

funcMap := template.FuncMap{
    "escapeYAML":     escapeYAML,
    "escapeMarkdown": escapeMarkdown,
    "escapeTOML":     escapeTOML,
}

Escape Functions¶

All escape functions are pure and infallible. They accept any string and return a string that is safe to interpolate into the named context. Invalid bytes (e.g. invalid UTF-8) are replaced with the Unicode replacement character (\uFFFD) rather than returned verbatim.

escapeYAML(s string) string — For YAML string values in block scalar context: - Always wrap the result in double quotes. Unlike the original "quote if needed" approach, unconditional quoting is simpler, auditable, and robust across YAML 1.1 and 1.2 parsers (both resolve yes/no as booleans under certain tags, and implicit typing rules differ). - Inside the quoted string: escape \ as \\, " as \", and control characters (0x00–0x1F, 0x7F) as \xHH escapes. - Strip NUL bytes (they cannot appear in YAML even when escaped, per the YAML 1.2 character-set production).

escapeMarkdown(s string) string — For Markdown prose contexts (NOT code blocks or headings): - Escape CommonMark punctuation that initiates a construct: \, `, *, _, [, ], <, >, |, {, }, !, #. - Do NOT escape ., -, + universally — these only have meaning at line-start or in specific positions, and universal escaping corrupts ordinary prose (e.g. v1.0.0 becomes v1\.0\.0). The template writer is responsible for placing escapeMarkdown only in inline-prose contexts. - Replace \r\n and \r with \n; then each \n is preserved as-is (Markdown line breaks are benign in prose).

escapeMarkdownCodeBlock(s string) string — For Markdown inside a fenced code block: - Code blocks render content verbatim but an input containing ` would close the block. Replace runs of 3+ backticks with `\ sequences. - Strip NUL bytes and normalise line endings.

escapeTOML(s string) string — For TOML basic string values ("..."): - Escape \, ", and control characters using TOML escape sequences (\\, \", \b, \t, \n, \f, \r, \uHHHH). - Per TOML spec, DEL (0x7F) and other control characters must be escaped.

escapeComment(s string) string — For single-line comments (justfile #, YAML #, CODEOWNERS #): - Replace all newline sequences with a single space. A newline in a comment allows the next line to escape comment context and inject content. - Replace NUL bytes with space.

escapeShellArg(s string) string — For shell-like contexts where values are not in quoted arguments (justfile recipe bodies): - exec.Command does not invoke a shell, but just recipes execute under sh by default. Any user input interpolated into a recipe body could reach the shell. - Wrap the value in single quotes; escape existing single quotes as '\''. - Only used in the justfile template; currently no user field reaches a shell command body (all Name uses are inside binary paths which validation already constrains to [a-z0-9-]).

Identity guarantee: For any string matching ^[a-zA-Z0-9 _.,/-]*$ (the "safe" character class), every escape function returns the input unchanged. Existing generated projects with clean inputs will see no diff after this change.

Template Changes¶

Example changes to skeleton templates:

# README.md -- Markdown context
# {{ .Name | escapeMarkdown }}

{{ .Name | escapeMarkdown }} is a tool built with [gtb](...).

# zensical.toml -- TOML string values
site_name = "{{ .Name | escapeTOML }}"
site_description = "{{ .Description | escapeTOML }}"
site_author = "{{ .Org | escapeTOML }}"

# .goreleaser.yaml -- mixed contexts
# YAML value (non-code): project_name is a display name
project_name: {{ .Name | escapeYAML }}
# Code path (must not escape): build main path
    main: cmd/{{ .Name }}/main.go

# justfile -- mixed contexts
# Build the {{ .Name | escapeComment }} binary   <-- comment (non-code)
build: tidy generate
    go build -o bin/{{ .Name }} ./cmd/{{ .Name }}  <-- code path (no escape)

Integration with Template Rendering¶

The renderAndHashSkeletonTemplate function in skeleton.go currently creates a bare text/template. It must be updated to register the function map:

tmpl, err := template.New(fullPath).Funcs(templateFuncMap).Parse(tmplStr)

The templateFuncMap is a package-level variable containing all escape functions, defined in a new file internal/generator/template_escape.go.

The inline template strings (SkeletonGoMod, SkeletonConfig) must also have the function map available. Since SkeletonConfig currently contains no user data, only SkeletonGoMod needs consideration -- and its fields (ModulePath, GoVersion) appear in code-context locations, so no escaping is applied there.

Project Structure¶

Generator Impact¶

This change modifies generator template output. After implementation:

1. Existing projects regenerated with gtb regenerate will see minor diffs in non-code locations (added escaping). These are cosmetic for clean inputs and protective for adversarial inputs.
2. The conflict detection system (hash-based) will detect these as generator-side changes and prompt appropriately.
3. No changes to the manifest format or feature flags.

Error Handling¶

• Escape functions must be pure and infallible (no error returns). Invalid input is sanitised, never rejected, at the template layer.
• Input validation (rejecting clearly invalid names, channels, etc.) is a separate concern to be addressed in a follow-up spec. This spec focuses solely on defence-in-depth at the template rendering layer.

Testing Strategy¶

Unit Tests — Validation (internal/generator/validate_test.go)¶

Table-driven tests for each field validator:

Adversarial input tests include: NUL bytes, CR/LF injection, right-to-left override (\u202E), zero-width joiner (\u200D), BOM (\uFEFF), combining diacritics, and CJK homoglyphs.

Unit Tests — Escape Functions (internal/generator/template_escape_test.go)¶

Table-driven tests for each escape function:

Fuzz Tests (template_escape_fuzz_test.go)¶

Required for Phase 1. For each escape function:

func FuzzEscapeYAML(f *testing.F) {
    f.Add("plain")
    f.Add("key: value")
    f.Add("line1\nline2")
    f.Fuzz(func(t *testing.T, s string) {
        out := escapeYAML(s)
        // Property 1: output must parse as a valid YAML scalar
        var parsed string
        if err := yaml.Unmarshal([]byte(`v: `+out), &struct{ V *string }{V: &parsed}); err != nil {
            t.Errorf("escapeYAML produced unparseable output for input %q: %v", s, err)
        }
        // Property 2: never panics (implicit — Fuzz would catch a panic)
        // Property 3: the parsed value must round-trip to something lossy-equivalent
        //            to the input (e.g. NUL bytes stripped is acceptable)
    })
}

Equivalent fuzz tests exist for escapeTOML (property: output parses as TOML scalar), escapeMarkdown (property: does not produce unbalanced link/code constructs), and escapeShellArg (property: surviving shell tokenisation yields exactly one argument equal to or lossy-equivalent to input).

Fuzz corpus is seeded with known-problematic inputs from the unit test tables.

Integration Tests¶

• Render each modified skeleton template with adversarial input data (where input validation would reject them, the test uses a lower-level API that bypasses validation) and verify the rendered output is syntactically valid (YAML parses, TOML parses, Markdown renders without injection).
• Verify code-location outputs remain unescaped and functional by running go build, yamllint, and tomli (or github.com/pelletier/go-toml parser) on the rendered files.
• Verify that Name = "../../etc/passwd" or similar is rejected at input validation and never reaches the template layer. This is the primary integration assertion.

Regression Tests¶

• Generate a full skeleton with normal input values and verify the output is byte-identical to pre-change output. Escape functions are identity for the safe character class, so output should not change for any existing test fixture.
• Hash-verify every rendered file against stored golden hashes. If a golden hash changes, CI fails and the reviewer must confirm the change is expected.

Regeneration Compatibility¶

The generator's hash-based conflict detection (see internal/generator/manifest.go) tracks per-file hashes. Adding escape functions changes output for adversarial inputs but not for clean inputs. Regression tests confirm no hash drift for all existing fixtures.

Migration & Compatibility¶

• Backward compatible: Clean input values produce identical output (escape functions are identity for safe strings).
• No API changes: Entirely internal to internal/generator/.
• No manifest changes: File hashes will differ only if templates produce different output for the same input, which only happens for inputs containing special characters.
• Regeneration safe: Existing projects with clean inputs will see no hash mismatches after this change.
• Validation may reject previously-accepted inputs: Users whose tool Name, Org, Host, etc. contain now-disallowed characters will see a validation error on regeneration. The error message surfaces the exact rule and the offending input; the migration guide documents the rules and offers workarounds (e.g. punycode for Unicode hosts).

Non-Functional Requirements¶

Testing & Quality Gates¶

Documentation Deliverables¶

The following artefacts must be produced or updated before the implementing PR is merged:

Observability¶

Performance Bounds¶

Security Invariants¶

Summarised from the Threat Model and Resolved Decisions:

1. Every user-provided field has an explicit validation rule. Accepting any new user field requires updating internal/generator/validate.go in the same PR.
2. Escape functions are identity on the safe character class and idempotent on any input.
3. NFC normalisation happens before validation so homoglyphs fail fast.
4. Code-context template sites never receive escaped input; non-code sites always do (defence-in-depth even when validation covers the character class).
5. Jennifer-generated Go (skeleton_root.go) handles its own literal escaping via jen.Lit(). Any new user field routed through jennifer must be validated even if no escape function applies.
6. Validation errors never echo the offending value at log levels above DEBUG.

Future Considerations¶

1. Input validation at the wizard/flag layer: A complementary spec could add validation rules to SkeletonOptions.ValidateOrPrompt() that reject or warn about inputs containing template-sensitive characters. This provides defence at the entry point rather than just the rendering layer.
2. Fuzz testing: The escape functions are good candidates for Go fuzz testing to discover edge cases in escaping logic.
3. Centralised template rendering: If the generator gains more template-rendered outputs in the future, the function map registration should be centralised (this spec already proposes a package-level templateFuncMap).
4. Content Security Policy for Markdown: If generated documentation is ever served in a web context, additional XSS protections may be needed.

Implementation Phases¶

Phase 1: Input Validation and Escape Functions¶

Validation is the primary defence; it ships first so no further changes can introduce adversarial inputs to the rendering layer.

1. Create internal/generator/validate.go with field validators (see Input Validation section).
2. Create internal/generator/validate_test.go with comprehensive unit tests (including adversarial Unicode cases).
3. Wire validators into SkeletonOptions.ValidateOrPrompt and the manifest-loading paths in regenerate.go.
4. Create internal/generator/template_escape.go with escapeYAML, escapeMarkdown, escapeMarkdownCodeBlock, escapeTOML, escapeComment, escapeShellArg, and templateFuncMap.
5. Create internal/generator/template_escape_test.go with comprehensive unit tests.
6. Create internal/generator/template_escape_fuzz_test.go with fuzz tests for each escape function.
7. Modify skeleton.go to register templateFuncMap in renderAndHashSkeletonTemplate — and in the inline template strings (SkeletonGoMod, SkeletonConfig) for consistency, even though they currently use only code-context fields.
8. Run existing test suite; no functional change to rendered output expected.

Phase 2: Apply Escaping to Skeleton Templates¶

Now that validation rejects most adversarial inputs, escaping at non-code sites provides defence-in-depth.

1. Update each skeleton template file to use escape functions at non-code call sites (see Project Structure table).
2. Add integration tests rendering templates with adversarial input (bypassing validation at a lower-level API) and asserting valid YAML/TOML/Markdown.
3. Add regression tests confirming clean-input output is byte-identical to pre-change output.
4. Add golden-hash regression on every skeleton file.

Phase 3: Continuous Improvement¶

Tracked as follow-ups rather than required work:

1. Add a --no-validate flag (or environment variable) for CI/automation paths that trust their inputs. Default remains strict.
2. Centralise validation rules if other parts of the codebase (AI wizard, config init) collect similar fields.
3. Consider CLDR-based Unicode validation for fields like Description that allow Unicode but must still be safe for display in terminals and web UIs.

Resolved Decisions¶

1. Name is restricted to ^[a-z][a-z0-9-]{0,63}$ at input time. This eliminates path traversal, Unicode spoofing, shell/YAML/TOML/Markdown injection, and invalid-Go-identifier issues in a single check. Most other escaping concerns for Name become moot. The restriction is tighter than Go identifier rules (no underscores, no uppercase) to enforce consistent naming across binaries, config paths, and URLs.

2. Host is validated as an RFC 1123 hostname (optionally with :port) at input time. Punycode (xn--...) is accepted so internationalised hosts are supported. Raw Unicode hosts are rejected — the tool author must convert to punycode explicitly, preventing homoglyph attacks. In templates, Host is treated as trusted (no escape pipe needed) because validation has already constrained the character class.

3. Org is validated against GitHub org rules (^[a-zA-Z0-9][a-zA-Z0-9-]{0,38}$) for github release provider, and GitLab namespace rules ([a-zA-Z0-9][a-zA-Z0-9/-]{0,254} with /-segment depth ≤ 4) for gitlab. CODEOWNERS injection is prevented by validation alone; no runtime escape is applied to Org.

4. Escaping is universal at non-code sites even for validated fields. Validation eliminates known injection vectors, but escape functions are cheap (identity on safe input) and protect against future field additions or relaxed validation. Defence-in-depth is preferred over trusting a single layer.

5. EnvPrefix, Slack/Teams, and telemetry-endpoint fields are validated and flow only through jennifer. They are not currently used in text templates, but this spec adds validation so that if future changes add them to text templates, the entry point is already safe.