099-programmable-templates.rst (6831B)
1 .. _dd-99: 2 3 DD 99: Programmable Template Validation 4 ####################################### 5 6 :Design status: Draft 7 :Implementation status: Not started 8 :DD shepherd: TBD 9 :Historical contributors: Bohdan Potuzhnyi 10 :First published: 2026-07-23 11 :Last substantive change: 2026-07-23 12 13 Summary 14 ======= 15 16 This document sketches programmable validation for merchant templates. 17 A locally configured Bash script examines a proposed order after normal 18 template processing and either permits or rejects order creation. 19 20 .. warning:: 21 22 This is an early design sketch. It does not yet define a protocol version, 23 complete input schema or stable configuration API. 24 25 Motivation 26 ========== 27 28 Merchant templates cover common ways of turning client input into an order, 29 but some deployments have local conditions that are too specific for the 30 generic merchant protocol. Examples include checking an institution's local 31 campaign rules, validating a site-specific reference or applying a temporary 32 business restriction. 33 34 Adding every local rule to the merchant backend would make the protocol and 35 implementation increasingly specialized. Programmable template validation 36 would instead let an administrator associate a local Bash script with a 37 template. The script examines a proposed order and either allows or rejects 38 its creation. 39 40 Requirements 41 ============ 42 43 * Normal merchant template validation must run before a custom validator. 44 45 * A validator must be a Bash script configured locally by the merchant 46 operator. 47 48 * The script must initially be limited to allowing or rejecting an order. 49 50 * Script input must use a structured, versioned JSON interface. 51 52 * Failure, timeout or malformed output must reject order creation. 53 54 * Scripts must run with strict time and resource limits. 55 56 * Scripts must not receive merchant secrets or unrelated customer data. 57 58 * Installing or changing scripts must require an administrative 59 permission and produce an audit record. 60 61 Proposed Solution 62 ================= 63 64 The merchant backend performs its normal template processing first: 65 66 1. It parses and validates the template instantiation request. 67 68 2. It resolves products and constructs the proposed contract terms. 69 70 3. If the template has a configured validation script, the backend invokes 71 it with the proposed order as versioned JSON on standard input. 72 73 4. An exit status of zero allows the order. Any other exit status rejects 74 it. 75 76 5. Only an allowed proposal is persisted as an order. 77 78 The script is validation-only. Allowing scripts to rewrite 79 contract terms would make it harder to reason about signatures, totals and 80 which component owns protocol validation. A later design may introduce 81 carefully constrained transformations if concrete use cases require them. 82 83 Script Configuration and Invocation 84 ----------------------------------- 85 86 The merchant operator associates an absolute Bash script path with a 87 template. This is server-side configuration and must never be supplied by a 88 client while instantiating the template. The backend invokes the configured 89 file using a fixed command equivalent to: 90 91 .. code-block:: console 92 93 /bin/bash /configured/path/validate-template.sh 94 95 The backend must not construct a shell command from template request values. 96 The script receives no request-derived command-line arguments. A versioned 97 JSON object is written to its standard input and may contain: 98 99 * the merchant instance and template identifiers; 100 101 * the normalized template request; 102 103 * the proposed contract terms; 104 105 * the current time and a small, explicitly defined execution context; and 106 107 * a version number for the validator input schema. 108 109 It must not contain merchant private keys, database credentials or unrelated 110 customer data. 111 112 The script communicates its decision through its exit status: 113 114 * Exit status 0 permits creation of the proposed order. 115 116 * Any non-zero exit status rejects order creation. 117 118 Standard output is ignored in the initial design. A bounded amount of 119 standard error may be recorded in merchant logs for administrators, but must 120 not automatically be returned to an untrusted client. 121 122 Execution Requirements 123 ---------------------- 124 125 Script execution must be bounded by a short timeout and strict resource 126 limits. Failure, timeout and non-zero process termination must deny order 127 creation. 128 129 Network and filesystem access should be disabled by default. If a deployment 130 needs external state, access should be explicitly configured and documented 131 rather than inherited from the merchant backend process. 132 133 The script runs with a minimal environment and a dedicated unprivileged 134 service account. The backend must not pass authentication tokens, database 135 credentials or other ambient secrets through environment variables. 136 137 Configuration and operation of scripts require an administrative 138 permission separate from ordinary template use. Logs should identify the 139 template, script and outcome without recording complete contract terms or 140 sensitive request values by default. 141 142 Open Design Work 143 ================ 144 145 The following points require concrete use cases and implementation 146 experiments: 147 148 * the exact versioned input schema; 149 150 * how scripts are installed, selected and updated; 151 152 * which merchant API error represents rejection by a script; 153 154 * whether controlled read-only access to local data is necessary; 155 156 * how deterministic behavior and reproducible debugging are achieved; and 157 158 * whether any future version should permit constrained modifications to the 159 proposed contract. 160 161 Security Considerations 162 ======================= 163 164 A script runs on the order-creation path and is therefore both a security 165 boundary and a denial-of-service risk. It must not execute with the merchant 166 backend's full authority. Resource limits and fail-closed behavior are 167 mandatory. Bash is not itself a sandbox, so the operating system must enforce 168 the configured process, filesystem and network restrictions. 169 170 Script updates can change which orders a merchant accepts. Configuration 171 changes therefore need authentication, audit records and an explicit rollback 172 mechanism. 173 174 Test Plan 175 ========= 176 177 An eventual implementation should test exit status zero and non-zero, 178 timeouts, missing or unreadable scripts, process failures, resource 179 exhaustion and attempts to use forbidden network or filesystem access. It 180 should also verify the JSON input, confirm that rejected orders are not 181 partially persisted and ensure that diagnostics do not leak sensitive 182 contract data. 183 184 Definition of Done 185 ================== 186 187 This design is ready for implementation only after the versioned input 188 schema, script configuration, permission model, error mapping and operating 189 system restrictions are specified precisely. At least one real deployment 190 rule must be implemented as a Bash script to validate the interface before it 191 becomes a stable merchant feature.