DD 99: Programmable Template Validation

20.99. DD 99: Programmable Template Validation#

20.99.1. Summary#

This document sketches programmable validation for merchant templates. A locally configured Bash script examines a proposed order after normal template processing and either permits or rejects order creation.

Warning

This is an early design sketch. It does not yet define a protocol version, complete input schema or stable configuration API.

20.99.2. Motivation#

Merchant templates cover common ways of turning client input into an order, but some deployments have local conditions that are too specific for the generic merchant protocol. Examples include checking an institution’s local campaign rules, validating a site-specific reference or applying a temporary business restriction.

Adding every local rule to the merchant backend would make the protocol and implementation increasingly specialized. Programmable template validation would instead let an administrator associate a local Bash script with a template. The script examines a proposed order and either allows or rejects its creation.

20.99.3. Requirements#

  • Normal merchant template validation must run before a custom validator.

  • A validator must be a Bash script configured locally by the merchant operator.

  • The script must initially be limited to allowing or rejecting an order.

  • Script input must use a structured, versioned JSON interface.

  • Failure, timeout or malformed output must reject order creation.

  • Scripts must run with strict time and resource limits.

  • Scripts must not receive merchant secrets or unrelated customer data.

  • Installing or changing scripts must require an administrative permission and produce an audit record.

20.99.4. Proposed Solution#

The merchant backend performs its normal template processing first:

  1. It parses and validates the template instantiation request.

  2. It resolves products and constructs the proposed contract terms.

  3. If the template has a configured validation script, the backend invokes it with the proposed order as versioned JSON on standard input.

  4. An exit status of zero allows the order. Any other exit status rejects it.

  5. Only an allowed proposal is persisted as an order.

The script is validation-only. Allowing scripts to rewrite contract terms would make it harder to reason about signatures, totals and which component owns protocol validation. A later design may introduce carefully constrained transformations if concrete use cases require them.

20.99.4.1. Script Configuration and Invocation#

The merchant operator associates an absolute Bash script path with a template. This is server-side configuration and must never be supplied by a client while instantiating the template. The backend invokes the configured file using a fixed command equivalent to:

/bin/bash /configured/path/validate-template.sh

The backend must not construct a shell command from template request values. The script receives no request-derived command-line arguments. A versioned JSON object is written to its standard input and may contain:

  • the merchant instance and template identifiers;

  • the normalized template request;

  • the proposed contract terms;

  • the current time and a small, explicitly defined execution context; and

  • a version number for the validator input schema.

It must not contain merchant private keys, database credentials or unrelated customer data.

The script communicates its decision through its exit status:

  • Exit status 0 permits creation of the proposed order.

  • Any non-zero exit status rejects order creation.

Standard output is ignored in the initial design. A bounded amount of standard error may be recorded in merchant logs for administrators, but must not automatically be returned to an untrusted client.

20.99.4.2. Execution Requirements#

Script execution must be bounded by a short timeout and strict resource limits. Failure, timeout and non-zero process termination must deny order creation.

Network and filesystem access should be disabled by default. If a deployment needs external state, access should be explicitly configured and documented rather than inherited from the merchant backend process.

The script runs with a minimal environment and a dedicated unprivileged service account. The backend must not pass authentication tokens, database credentials or other ambient secrets through environment variables.

Configuration and operation of scripts require an administrative permission separate from ordinary template use. Logs should identify the template, script and outcome without recording complete contract terms or sensitive request values by default.

20.99.5. Open Design Work#

The following points require concrete use cases and implementation experiments:

  • the exact versioned input schema;

  • how scripts are installed, selected and updated;

  • which merchant API error represents rejection by a script;

  • whether controlled read-only access to local data is necessary;

  • how deterministic behavior and reproducible debugging are achieved; and

  • whether any future version should permit constrained modifications to the proposed contract.

20.99.6. Security Considerations#

A script runs on the order-creation path and is therefore both a security boundary and a denial-of-service risk. It must not execute with the merchant backend’s full authority. Resource limits and fail-closed behavior are mandatory. Bash is not itself a sandbox, so the operating system must enforce the configured process, filesystem and network restrictions.

Script updates can change which orders a merchant accepts. Configuration changes therefore need authentication, audit records and an explicit rollback mechanism.

20.99.7. Test Plan#

An eventual implementation should test exit status zero and non-zero, timeouts, missing or unreadable scripts, process failures, resource exhaustion and attempts to use forbidden network or filesystem access. It should also verify the JSON input, confirm that rejected orders are not partially persisted and ensure that diagnostics do not leak sensitive contract data.

20.99.8. Definition of Done#

This design is ready for implementation only after the versioned input schema, script configuration, permission model, error mapping and operating system restrictions are specified precisely. At least one real deployment rule must be implemented as a Bash script to validate the interface before it becomes a stable merchant feature.