Skip to main content
Hyperterse uses textual substitution for {{ inputs.field }} placeholders. Before a statement reaches the connector driver, the executor performs two passes:
  1. Environment substitution — {{ env.VAR }} placeholders are replaced with process environment values.
  2. Input substitution — {{ inputs.field }} placeholders are replaced with string representations of validated input values.
The resulting statement is a complete string passed to the connector’s Execute method. No parameterized query binding occurs at the substitution layer.

​
Implications

  • Values are inserted directly into the statement text.
  • The connector receives the statement as a single string.
  • Statement safety depends on query design and input validation.
  • This is functionally equivalent to string interpolation — it does not provide prepared-statement injection protection.

​
Built-in protections

The runtime validates and sanitizes inputs before they reach connectors or scripts.

​
Input type validation

CheckBehavior
Required inputsMissing required inputs produce an error before execution.
Type conversionValues are converted to the declared type. Invalid conversions produce a type error.
Default applicationOmitted optional inputs with defaults receive the default value.
Type validation constrains the value space: an int input only accepts numbers, a boolean only accepts true/false. This eliminates injection risk for non-string types.

​
Credential isolation

  • Connection strings are server-side only.
  • Auth policy values are resolved from environment variables and never returned in responses.
  • Trace attributes redact sensitive values.

​
Auth enforcement

  • Tool-level auth runs before any input processing.
  • Auth failures halt the pipeline immediately.

​
What the framework does not protect against

  • SQL injection via string inputs. A string-typed input has no content restriction. Malicious SQL can be injected through string placeholders.
  • Statement manipulation via crafted values. Any input that contributes to statement structure (not just data values) is an injection vector.
  • Business logic abuse. Negative IDs, excessive limits, and semantically invalid values are not caught by type validation.

​
Defensive patterns

Apply the following practices to minimize the surface area exposed to untrusted input.

​
Use strict types

Prefer int, float, and boolean over string. Numeric and boolean types have constrained value spaces. 
inputs:
  user_id:
    type: int
  active:
    type: boolean

​
Validate strings in transforms

For string-typed inputs, validate format in an input transform: 
export default function inputTransform(payload: {
  inputs: Record<string, any>
  tool: string
}) {
  const { email } = payload.inputs

  if (
    typeof email !== 'string' ||
    !email.match(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/)
  ) {
    throw new Error('Invalid email format')
  }

  return payload.inputs
}

​
Keep statements narrow

Use inputs only in value positions: 
# Safe: input as a WHERE value
statement: "SELECT * FROM users WHERE id = {{ inputs.user_id }}"

# Dangerous: input as a table or column name
statement: "SELECT * FROM {{ inputs.table_name }}"

​
Use handlers for dynamic queries

When a query needs dynamic structure, implement it as a handler with explicit sanitization: 
export default async function handler(payload: {
  inputs: Record<string, any>
  tool: string
}) {
  const { user_id, fields } = payload.inputs

  const allowedFields = ['id', 'name', 'email', 'created_at']
  const selectedFields = fields.filter((f: string) => allowedFields.includes(f))
  // Construct query with validated field list
}

​
Deploy behind a gateway

Place the runtime behind an API gateway or reverse proxy with rate limiting, request size limits, IP access control, and TLS termination.

​
Environment variable safety

{{ env.VAR }} values are substituted without sanitization. If a variable contains SQL-significant characters and is used in a statement, the same injection risk applies. Missing variables fail execution rather than defaulting to empty strings.

​
Responsibility matrix

LayerProtectionResponsibility
Input type validationType conversion and required checksFramework (automatic)
Credential isolationConnection strings hidden from callersFramework (automatic)
Auth enforcementPre-execution access controlFramework (configured per-tool)
String input sanitizationContent validation and format enforcementDeveloper (input transforms)
Statement safetyAvoiding structural injectionDeveloper (query design)
Network securityTLS, rate limiting, access controlOperator (infrastructure)